REST API

Used to interact with our server-side software.
The REST API is used mainly to scan (map) a space and construct a map of it. It's also used
to download maps from our server at runtime for visual positioning (localization).
The maps can also be downloaded from the Developer Portal for offline and embedded use.
All REST API calls take JSON as input and also return the result as JSON.
All calls, except login, need a valid developer token for authentication.
Sample Code
The code below is an example of using the REST API to log in a user and retrieving their token.
See the Immersal.Samples.Mapping.Mapper class and Samples/Scenes/MappingApp for more examples.
SDKLoginRequest loginRequest = new SDKLoginRequest();
loginRequest.login = "your@email.address";
loginRequest.password = "password";
​
string jsonString = JsonUtility.ToJson(loginRequest);
byte[] myData = System.Text.Encoding.UTF8.GetBytes(jsonString);
using (UnityWebRequest request = UnityWebRequest.Put(string.Format("{0}/{1}", m_server, "fcgi?6"), jsonString))
{
  request.method = UnityWebRequest.kHttpVerbPOST;
  request.useHttpContinue = false;
  request.SetRequestHeader("Content-Type", "application/json");
  request.SetRequestHeader("Accept", "application/json");
  yield return request.SendWebRequest();
​
  SDKLoginResult loginResult = JsonUtility.FromJson<SDKLoginResult>(request.downloadHandler.text);
  if (loginResult.error == "none")
  {
    Debug.Log(loginResult.token);
  }
}
Login
 Log in request / response
[Serializable]
public class SDKLoginRequest
{
    public string login;
    public string password;
}
​
[Serializable]
public class SDKLoginResult
{
    public string error;  // "none" | "auth"
    public string token;  // developer token
    public int banks;     // number of image banks, limited to 1 in Early Access
}
Clear the Image Bank
 Clear request / response
[Serializable]
public class SDKClearRequest
{
    public string token;
    public int bank;        // id of image bank to clear
    public bool anchor;     // if true, clears also anchor points (i.e. empty cloud)
}
​
[Serializable]
public class SDKClearResult
{
    public string error;
}
Construct a Map
 Construct request / response
[Serializable]
public class SDKConstructRequest
{
    public string token;
    public int bank;        // id of image bank
    public string name;     // name for the map
}
​
[Serializable]
public class SDKConstructResult
{
    public string error;
    public int size;        // number of images used to create the map
}
Construct Job
 Represents a server job that is calculating the map
[Serializable]
public class SDKJob
{
    public int id;
    public int size;
    public int bank;
    public string work;
    public string status;   // "done" | "processing" | "failed" | "pending"
    public string server;
    public string name;
    public string created;
    public string modified;
}
Load Latest Map
Load latest request / response
[Serializable]
public class SDKLoadLatestRequest
{
    public string token;
    public int bank;
}
​
[Serializable]
public class SDKLoadLatestResult
{
    public string error;
    public int count;
    public SDKJob[] jobs;
}
Status
Status request / response
[Serializable]
public class SDKStatusRequest
{
    public string token;
    public int bank;
}
​
[Serializable]
public class SDKStatusResult
{
    public string error;
    public int imageCount;
    public int bankMax;
    public int imageMax;
    public bool eulaAccepted;
}
List of All Jobs
Jobs request / response
[Serializable]
public class SDKJobsRequest
{
    public string token;
    public int bank;
}
​
[Serializable]
public class SDKJobsResult
{
    public string error;
    public int count;
    public SDKJob[] jobs;
}
Save Captured Image to the Map
 Image request / response
[Serializable]
public class SDKImageRequest
{
    public string token;
    public int bank;
    public int run;
    public int index;
    public bool anchor;
    public double px;
    public double py;
    public double pz;
    public double r00;
    public double r01;
    public double r02;
    public double r10;
    public double r11;
    public double r12;
    public double r20;
    public double r21;
    public double r22;
    public double fx;
    public double fy;
    public double ox;
    public double oy;
    public string b64;
}
​
[Serializable]
public class SDKImageResult
{
    public string error;
    public string path;
}
Load Constructed Map
 Map request / response
[Serializable]
public class SDKMapRequest
{
    public string token;
    public int id;
}
​
[Serializable]
public class SDKMapResult
{
    public string error;
    public string b64;
}
Errors
The REST API uses the following error codes (TBD):

 Error Code
 Meaning
400
Bad Request -- Your request is invalid.
​
API Documentation - Previous
Core Plugin API
Next - Developer Feedback
Support
Last updated 2 months ago