REST API

The REST API is used to interact with the Immersal Cloud Service.
You can use it to submit images for Spatial Map construction, modify and load Maps, and even use the on-server Visual Positioning.
All REST API requests take JSON as input and also return the result as JSON
All requests, except login, need a valid developer token for authentication. You can get it by logging in or from the Developer Portal​
We provide a sample implementation for Unity in C#, see the REST.cs and RESTJobsAsync.cs classes in the Immersal SDK Core .unitypackage
We also provide basic Python examples in this documentation.
It should also be quite straightforward to make the API calls in JSON from e.g. JavaScript & WebXR applications, and on other platforms.
API Methods
post
https://api.immersal.com
/login
Login
post
https://api.immersal.com
/status
Account Status
post
https://api.immersal.com
/list
List Jobs
post
https://api.immersal.com
/geolist
List Jobs (GPS)
post
https://api.immersal.com
/captureb64
Capture Image
post
https://api.immersal.com
/construct
Map Construct
post
https://api.immersal.com
/clear
Clear Workspace
post
https://api.immersal.com
/localizeb64
Localize Image
post
https://api.immersal.com
/geolocalizeb64
Localize Image (GPS)
post
https://api.immersal.com
/mapb64
Load Map
post
https://api.immersal.com
/delete
Delete Map
post
https://api.immersal.com
/restore
Restore Images
post
https://api.immersal.com
/ecef
Map ECEF (GPS)
C# Sample Code
The code below is an example of using the REST API to log in a user and retrieving their token. Except for the SDKLoginRequest class, all other Request classes inherit the requisite token from SDKRequestBase.
See the Immersal.Samples.Mapping.MapperJobs and Immersal.Samples.Mapping.Mapper classes and Samples/Scenes/MappingApp for more examples.
1
SDKLoginRequest loginRequest = new SDKLoginRequest();
2
loginRequest.login = "[email protected]";
3
loginRequest.password = "password";
4
​
5
string jsonString = JsonUtility.ToJson(loginRequest);
6
using (UnityWebRequest request = UnityWebRequest.Put(string.Format(Endpoint.URL_FORMAT, m_Sdk.localizationServer, Endpoint.LOGIN), jsonString))
7
{
8
  request.method = UnityWebRequest.kHttpVerbPOST;
9
  request.useHttpContinue = false;
10
  request.SetRequestHeader("Content-Type", "application/json");
11
  request.SetRequestHeader("Accept", "application/json");
12
  yield return request.SendWebRequest();
13
​
14
  SDKLoginResult loginResult = JsonUtility.FromJson<SDKLoginResult>(request.downloadHandler.text);
15
  if (loginResult.error == "none")
16
  {
17
    Debug.Log(loginResult.token);
18
  }
19
}
Copied!
Entities
Construct Job
Represents a server job that is calculating the map
1
[Serializable]
2
public class SDKJob
3
{
4
    public int id;
5
    public int size;
6
    public int bank;
7
    public string work;
8
    public string status;   // "done" | "sparse" | "processing" | "failed" | "pending"
9
    public string server;
10
    public string name;
11
    public double latitude;
12
    public double longitude;
13
    public double altitude;
14
    public string created;
15
    public string modified;
16
}
Copied!
Map Id
Encapsulates a map's ID, might be extended in the future. Currently only used in SDKLocalizeRequest. In JavaScript and other platforms, this could be represented as a typical JSON object, e.g. {"id": 6779}.
1
[Serializable]
2
public class SDKMapId
3
{
4
    public int id;
5
}
Copied!
Requests and Responses
Login
Log in request / response
1
[Serializable]
2
public class SDKLoginRequest
3
{
4
    public string login;
5
    public string password;
6
}
7
​
8
[Serializable]
9
public class SDKLoginResult
10
{
11
    public string error;  // "none" | "auth"
12
    public string token;  // developer token
13
    public int banks;     // number of image banks, limited to 1 currently
14
}
Copied!
Clear the Image Bank
Clear request / response
1
[Serializable]
2
public class SDKClearRequest : SDKRequestBase
3
{
4
    public int bank;        // id of image bank to clear
5
    public bool anchor;     // if true, clears also anchor points (i.e. empty cloud)
6
}
7
​
8
[Serializable]
9
public class SDKClearResult
10
{
11
    public string error;
12
}
Copied!
Construct a Map
Construct request / response
1
[Serializable]
2
public class SDKConstructRequest : SDKRequestBase
3
{
4
    public int bank;        // id of image bank
5
    public string name;     // name for the map
6
}
7
​
8
[Serializable]
9
public class SDKConstructResult
10
{
11
    public int id;          // id of the construction job / map
12
    public int size;        // number of images used to create the map
13
    public string error;
14
}
Copied!
Status
Status request / response
1
[Serializable]
2
public class SDKStatusRequest : SDKRequestBase
3
{
4
    public int bank;
5
}
6
​
7
[Serializable]
8
public class SDKStatusResult
9
{
10
    public int imageCount;
11
    public int bankMax;
12
    public int imageMax;
13
    public bool eulaAccepted;
14
    public string error;
15
}
Copied!
List of All Jobs
Jobs request / response
1
[Serializable]
2
public class SDKJobsRequest : SDKRequestBase
3
{
4
    public int bank;
5
}
6
​
7
[Serializable]
8
public class SDKJobsResult
9
{
10
    public int count;
11
    public SDKJob[] jobs;
12
    public string error;
13
}
Copied!
List of All Jobs (GPS)
The same as SDKJobsRequest, but only fetches the maps within the user's GPS location and range. If token is not given, all public maps will be fetched.
1
public class SDKGeoJobsRequest : SDKJobsRequest
2
{
3
    public double latitude;
4
    public double longitude;
5
    public double radius;
6
}
Copied!
Save Captured Image to the Map
Image request / response
1
[Serializable]
2
public class SDKImageRequest : SDKRequestBase
3
{
4
    public int bank;
5
    public int run;
6
    public int index;
7
    public bool anchor;
8
    public double px;    // camera x position
9
    public double py;    // camera y position
10
    public double pz;    // camera z position
11
    public double r00;   // rotation matrix row 0, col 0
12
    public double r01;   // rotation matrix row 0, col 1
13
    public double r02;   // rotation matrix row 0, col 2
14
    public double r10;   // rotation matrix row 1, col 0
15
    public double r11;   // rotation matrix row 1, col 1
16
    public double r12;   // rotation matrix row 1, col 2
17
    public double r20;   // rotation matrix row 2, col 0
18
    public double r21;   // rotation matrix row 2, col 1
19
    public double r22;   // rotation matrix row 2, col 2
20
    public double fx;    // camera intrinsics focal length x
21
    public double fy;    // camera intrinsics focal length y
22
    public double ox;    // camera intrinsics principal point x
23
    public double oy;    // camera intrinsics principal point y
24
    public double latitude;  // WGS84 latitude
25
    public double longitude; // WGS84 longitude
26
    public double altitude;  // GPS elevation
27
    public string b64;   // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
28
}
29
​
30
[Serializable]
31
public class SDKImageResult
32
{
33
    public string path;
34
}
Copied!
Localize Image
Localize request / response
The result (when localization has been successful) is a projection matrix in the AR Cloud space. It can be used to extract the position and rotation of the AR device, which then again can be combined with the device's local SLAM tracking.
1
[Serializable]
2
public class SDKLocalizeRequest : SDKRequestBase
3
{
4
    public double fx;    // camera intrinsics focal length x
5
    public double fy;    // camera intrinsics focal length y
6
    public double ox;    // camera intrinsics principal point x
7
    public double oy;    // camera intrinsics principal point y
8
    public string b64;   // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
9
    public SDKMapId[] mapIds;  // list of maps to localize against
10
}
11
​
12
[Serializable]
13
public class SDKLocalizeResult : SDKResultBase
14
{
15
    public bool success;
16
    public int map;     // ID of the map if localization was successful
17
    public float px;    // x position within the map
18
    public float py;    // y position within the map
19
    public float pz;    // z position within the map
20
    public float r00;   // rotation matrix row 0, col 0
21
    public float r01;   // rotation matrix row 0, col 1
22
    public float r02;   // rotation matrix row 0, col 2
23
    public float r10;   // rotation matrix row 1, col 0
24
    public float r11;   // rotation matrix row 1, col 1
25
    public float r12;   // rotation matrix row 1, col 2
26
    public float r20;   // rotation matrix row 2, col 0
27
    public float r21;   // rotation matrix row 2, col 1
28
    public float r22;   // rotation matrix row 2, col 2
29
}
Copied!
Localize Image (GPS)
Geo-localize request. The response is the same as with SDKLocalizeRequest.
This request localizes against maps within a given radius near the device's GPS coordinates. The mapIds array can be left empty in this case.
1
[Serializable]
2
public class SDKGeoLocalizeRequest : SDKLocalizeRequest
3
{
4
    public double latitude;
5
    public double longitude;
6
    public double radius;
7
}
Copied!
Map coordinates in ECEF system (GPS)
ECEF request / response
1
[Serializable]
2
public class SDKEcefRequest : SDKRequestBase
3
{
4
    public int id;    // map ID
5
}
6
​
7
[Serializable]
8
public class SDKEcefResult : SDKResultBase
9
{
10
    public double[] ecef;    // ECEF coordinates
11
}
Copied!
Delete Map
Delete map request / response
1
[Serializable]
2
public class SDKDeleteMapRequest : SDKRequestBase
3
{
4
    public int id;    // map ID
5
}
6
​
7
[Serializable]
8
public class SDKDeleteMapResult : SDKResultBase
9
{
10
​
11
}
Copied!
Restore Images
Restore map images request / response
After restoring the map's images, it is possible to add more images to the map and recalculate it.
1
    [Serializable]
2
    public class SDKRestoreMapImagesRequest : SDKRequestBase
3
    {
4
        public int id;    // map ID
5
    }
6
​
7
    [Serializable]
8
    public class SDKRestoreMapImagesResult : SDKResultBase
9
    {
10
​
11
    }
Copied!
Load Constructed Map
Map request / response
1
[Serializable]
2
public class SDKMapRequest : SDKRequestBase
3
{
4
    public int id;    // map ID
5
}
6
​
7
[Serializable]
8
public class SDKMapResult
9
{
10
    public string md5_al;    // MD5 hash for the loaded map
11
    public string b64;    // Base64 encoded .bytes map file
12
}
Copied!
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
Python examples
Last modified 6mo ago