REST API

Used to interact with the Immersal SDK Cloud Service.

The REST API is used to interact with the Immersal Cloud Service. It can be used to submit images for map construction, construct maps, load them, and even run the visual positioning localization process on the Cloud Service.

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.

We provide a sample implementation in C# (see the REST.cs class in the SDK samples). It should be quite straightforward to make the API calls in JSON from e.g. JavaScript & WebXR applications, and on other platforms.

API Methods

post
List Jobs

https://api.immersal.com/list
Returns a list of jobs (i.e., maps that are either ready or in different phases of construction).
Request
Response
Request
Form Data Parameters
token
required
string
A valid developer token
Response
200: OK
The response contains the job count and a list of all jobs.
{
"error": "none",
"count": 2,
"jobs": [{
"id": 9383,
"version": "1.8.0",
"creator": "[email protected]",
"bank": 0,
"size": 15,
"work": "/im/s00/job/IEuomF",
"status": "done",
"privacy": "0",
"server": "172.31.0.163",
"name": "TestMap",
"latitude": 60.163257817728663,
"longitude": 24.939001151402682,
"altitude": 19.666602622779706,
"created": "2020-09-11 13:56:51",
"modified": "2020-09-11 13:57:19",
"sha256_al": "3b1a83c27e6a61fa376dfe42d8196e076bd29e77ac133ba3531ac9385a5c1f66",
"sha256_sparse": "1d985d30ad2fcbbf5d08eb5bc78238e6c386d15eba796c0d36aaf3701477af1b",
"sha256_dense": "ef72bd391c92d365e86419ca22013c9ce709396c4372b5e5a8663127f961fdd3",
"sha256_tex": "c7d7638c3bdba3b18d37abee82d8b36e2e97312980590f455025faa51c816ac5"
}, {
"id": 8924,
"version": "1.7.0",
"creator": "[email protected]",
"bank": 0,
"size": 62,
"work": "/im/s00/job/QvkuFY",
"status": "done",
"privacy": "0",
"server": "172.31.22.8",
"name": "M01courtyard",
"latitude": 60.167185396129049,
"longitude": 24.922240769354836,
"altitude": 42.585041169197332,
"created": "2020-08-27 10:44:09",
"modified": "2020-08-27 10:44:09",
"sha256_al": "1ea5f978575651629c703b070acf95e4585864226fcde72674643c29a50893c4",
"sha256_sparse": "dc41d50657f503a3b78cd76895315097abb8b68846d7fefc26f873ae0eff7217",
"sha256_dense": "fa1d9667a338920ad65e955f36312feb06980edd3ff0c9ab0c6456a8c82a42ff",
"sha256_tex": ""
}]
}

post
Map Construct

https://api.immersal.com/construct
Starts a new map construction job.
Request
Response
Request
Form Data Parameters
featureCount
required
integer
Normal = 600, high = 1024
name
required
string
Map name
token
required
string
A valid developer token
Response
200: OK
Returns the ID of the constructed map and the number of images in it.
{
"error": "none",
"id": 7065,
"size: 300
}

post
List Jobs (GPS)

https://api.immersal.com/geolist
Returns a list of jobs (i.e., maps that are either ready or in different phases of construction). The map list is filtered by the given GPS coordinates and range (in metres). If token is not given, all public maps within the defined area will be listed.
Request
Response
Request
Path Parameters
optional
string
Form Data Parameters
radius
required
number
Search radius in metres
longitude
required
number
WGS84 longitude
latitude
required
number
WGS84 latitude
token
optional
string
A valid developer token, or empty
Response
200: OK
The response contains the job count and a list of all jobs.
{
"error": "none",
"count": 2,
"jobs": [{
"id": 9383,
"version": "1.8.0",
"creator": "[email protected]",
"bank": 0,
"size": 15,
"work": "/im/s00/job/IEuomF",
"status": "done",
"privacy": "0",
"server": "172.31.0.163",
"name": "TestMap",
"latitude": 60.163257817728663,
"longitude": 24.939001151402682,
"altitude": 19.666602622779706,
"created": "2020-09-11 13:56:51",
"modified": "2020-09-11 13:57:19",
"sha256_al": "3b1a83c27e6a61fa376dfe42d8196e076bd29e77ac133ba3531ac9385a5c1f66",
"sha256_sparse": "1d985d30ad2fcbbf5d08eb5bc78238e6c386d15eba796c0d36aaf3701477af1b",
"sha256_dense": "ef72bd391c92d365e86419ca22013c9ce709396c4372b5e5a8663127f961fdd3",
"sha256_tex": "c7d7638c3bdba3b18d37abee82d8b36e2e97312980590f455025faa51c816ac5"
}, {
"id": 8924,
"version": "1.7.0",
"creator": "[email protected]",
"bank": 0,
"size": 62,
"work": "/im/s00/job/QvkuFY",
"status": "done",
"privacy": "0",
"server": "172.31.22.8",
"name": "M01courtyard",
"latitude": 60.167185396129049,
"longitude": 24.922240769354836,
"altitude": 42.585041169197332,
"created": "2020-08-27 10:44:09",
"modified": "2020-08-27 10:44:09",
"sha256_al": "1ea5f978575651629c703b070acf95e4585864226fcde72674643c29a50893c4",
"sha256_sparse": "dc41d50657f503a3b78cd76895315097abb8b68846d7fefc26f873ae0eff7217",
"sha256_dense": "fa1d9667a338920ad65e955f36312feb06980edd3ff0c9ab0c6456a8c82a42ff",
"sha256_tex": ""
}]
}

post
Account Status

https://api.immersal.com/status
Gets the account's status.
Request
Response
Request
Form Data Parameters
token
required
string
A valid developer token.
Response
200: OK
Returns the number of images in the workspace, maximum number of image banks (currently 1), maximum number of images per map, and if the user has accepted the EULA.
{
"error": "none",
"imageCount": 5,
"bankMax": 1,
"imageMax": 256,
"eulaAccepted": true
}

post
Capture Image

https://api.immersal.com/captureb64
Saves the captured image with the camera position, orientation and intrinsics to the current mapping session.
Request
Response
Request
Form Data Parameters
b64
required
string
Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
altitude
optional
number
GPS elevation
longitude
optional
number
WGS84 longitude
latitude
optional
number
WGS84 latitude
oy
required
number
Camera intrinsics principal point y
ox
required
number
Camera intrinsics principal point x
fy
required
number
Camera intrinsics focal length y
fx
required
number
Camera intrinsics focal length x
r22
required
number
Rotation matrix row 2, col 2
r21
required
number
Rotation matrix row 2, col 1
r20
required
number
Rotation matrix row 2, col 0
r12
required
number
Rotation matrix row 1, col 2
r11
required
number
Rotation matrix row 1, col 1
r10
required
number
Rotation matrix row 1, col 0
r02
required
number
Rotation matrix row 0, col 2
r01
required
number
Rotation matrix row 0, col 1
r00
required
number
Rotation matrix row 0, col 0
pz
required
number
Camera z position
py
required
number
Camera y position
px
required
number
Camera x position
anchor
required
boolean
Is this an anchor image
index
required
integer
Image order index
run
required
integer
Image run, should be updated if the SLAM tracking is lost between images
bank
required
integer
Image bank, currently always 0
token
required
string
A valid developer token
Response
200: OK
{
"error": "none",
"path": "path_on_the_server"
}

post
Login

https://api.immersal.com/login
Log in to get a valid developer token, needed with the rest of the API calls.
Request
Response
Request
Form Data Parameters
login
required
string
Username (email address)
password
required
string
Password
Response
200: OK
{
"error": "none",
"token": "xyz",
"banks": 1 // number of image banks, limited to 1 currently
}
400: Bad Request
{
"error": "auth" // invalid username
}
{
"error": "password" // wrong password
}

post
Clear Workspace

https://api.immersal.com/clear
Deletes all the images from the workspace. Setting the anchor parameter to false will retain the anchor image.
Request
Response
Request
Form Data Parameters
anchor
required
boolean
Delete anchor image
token
required
string
A valid developer token
Response
200: OK
{
"error": "none"
}

post
Localize Image

https://api.immersal.com/localizeb64
Uses the on-server localizer to localize a camera image against a list of maps.
Request
Response
Request
Form Data Parameters
mapIds
required
array
An array of {"id": int} objects
param4
required
number
Magic param, defaults to 2.0
param3
required
number
Magic param, defaults to 0.0
param2
required
integer
Magic param, defaults to 12
param1
required
integer
Magic param, defaults to 0
b64
required
string
Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
oy
required
number
Camera intrinsics principal point y
ox
required
number
Camera intrinsics principal point x
fy
required
number
Camera intrinsics focal length y
token
required
string
A valid developer token
fx
required
number
Camera intrinsics focal length x
Response
200: OK
The response (when localization has been successful) is a projection matrix in the AR Cloud space. It can be used to extract the position and orientation of the device, which then again can be combined with the device's local SLAM tracking.
{
"error": "none",
"success": true,
"map": 7587,
"px": -0.5459369421005249,
"py": 0.0632220059633255,
"pz": 0.36885133385658264,
"r00": 0.68967300653457642,
"r01": 0.14381979405879974,
"r02": -0.709695041179657,
"r10": 0.0070222793146967888,
"r11": 0.97870355844497681,
"r12": 0.20515856146812439,
"r20": 0.7240869402885437,
"r21": -0.14647600054740906,
"r22": 0.67397546768188477
}

post
Localize Image (GPS)

https://api.immersal.com/geolocalizeb64
Uses the on-server localizer to localize a camera image against maps. The maps are filtered by the given WGS84 latitude, longitude, and radius. Localization is attempted against public maps and the user's private maps within these coordinates.
Request
Response
Request
Form Data Parameters
radius
required
number
Search radius in metres
longitude
required
number
WGS84 longitude
latitude
required
number
WGS84 latitude
param4
required
number
Magic param, defaults to 2.0
param3
required
number
Magic param, defaults to 0.0
param2
required
integer
Magic param, defaults to 12
param1
required
integer
Magic param, defaults to 0
b64
required
string
Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
token
required
string
A valid developer token
ox
required
number
Camera intrinsics principal point x
oy
required
number
Camera intrinsics principal point y
fy
required
number
Camera intrinsics focal length y
fx
required
number
Camera intrinsics focal length x
Response
200: OK
The response (when localization has been successful) is a projection matrix in the AR Cloud space. It can be used to extract the position and orientation of the device, which then again can be combined with the device's local SLAM tracking.
{
"error": "none",
"success": true,
"map": 7587,
"px": -0.5459369421005249,
"py": 0.0632220059633255,
"pz": 0.36885133385658264,
"r00": 0.68967300653457642,
"r01": 0.14381979405879974,
"r02": -0.709695041179657,
"r10": 0.0070222793146967888,
"r11": 0.97870355844497681,
"r12": 0.20515856146812439,
"r20": 0.7240869402885437,
"r21": -0.14647600054740906,
"r22": 0.67397546768188477
}

post
Load Map

https://api.immersal.com/mapb64
Load a previously constructed map from the cloud service. Only the user's own private/public and other users' public maps can be loaded.
Request
Response
Request
Form Data Parameters
id
required
integer
Map id
token
required
string
A valid developer token
Response
200: OK
The response is the binary map file (.bytes in the Developer Portal) Base64-encoded, and the file's SHA256 hash.
{
"error": "none",
"b64": "azdfazdf",
"sha256_al": "hash"
}

post
Delete Map

https://api.immersal.com/delete
Delete's the user's map from the cloud service.
Request
Response
Request
Form Data Parameters
id
required
integer
Map id
token
required
string
A valid developer token
Response
200: OK
{
"error": "none"
}

post
Restore Images

https://api.immersal.com/restore
Restores the images from a previously constructed map into the user's workspace, e.g., for adding additional images.
Request
Response
Request
Form Data Parameters
id
required
integer
Map id
token
required
string
A valid developer token
Response
200: OK
{
"error": "none"
}

post
Map ECEF (GPS)

https://api.immersal.com/ecef
Fetches the transform matrix from local map coordinates to global ECEF coordinates.
Request
Response
Request
Form Data Parameters
id
required
integer
Map id
token
required
string
A valid developer token
Response
200: OK
{
"error": "none",
"ecef":
[
2884704.4529634975,
1341415.1204073559,
5509576.2819128353,
0.48534169793128967,
0.87242347002029419,
0.05762564018368721,
0.23218682408332825,
-0.19214998185634613,
0.9535028338432312,
0.84293103218078613,
-0.44939476251602173,
-0.29582363367080688,
9.4544391632080078
]
}

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.

SDKLoginRequest loginRequest = new SDKLoginRequest();
loginRequest.login = "[email protected]";
loginRequest.password = "password";
string jsonString = JsonUtility.ToJson(loginRequest);
using (UnityWebRequest request = UnityWebRequest.Put(string.Format(Endpoint.URL_FORMAT, m_Sdk.localizationServer, Endpoint.LOGIN), 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);
}
}

Entities

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" | "sparse" | "processing" | "failed" | "pending"
public string server;
public string name;
public double latitude;
public double longitude;
public double altitude;
public string created;
public string modified;
}

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}.

[Serializable]
public class SDKMapId
{
public int id;
}

Requests and Responses

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 currently
}

Clear the Image Bank

Clear request / response

[Serializable]
public class SDKClearRequest : SDKRequestBase
{
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 : SDKRequestBase
{
public int bank; // id of image bank
public string name; // name for the map
}
[Serializable]
public class SDKConstructResult
{
public int id; // id of the construction job / map
public int size; // number of images used to create the map
public string error;
}

Status

Status request / response

[Serializable]
public class SDKStatusRequest : SDKRequestBase
{
public int bank;
}
[Serializable]
public class SDKStatusResult
{
public int imageCount;
public int bankMax;
public int imageMax;
public bool eulaAccepted;
public string error;
}

List of All Jobs

Jobs request / response

[Serializable]
public class SDKJobsRequest : SDKRequestBase
{
public int bank;
}
[Serializable]
public class SDKJobsResult
{
public int count;
public SDKJob[] jobs;
public string error;
}

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.

public class SDKGeoJobsRequest : SDKJobsRequest
{
public double latitude;
public double longitude;
public double radius;
}

Save Captured Image to the Map

Image request / response

[Serializable]
public class SDKImageRequest : SDKRequestBase
{
public int bank;
public int run;
public int index;
public bool anchor;
public double px; // camera x position
public double py; // camera y position
public double pz; // camera z position
public double r00; // rotation matrix row 0, col 0
public double r01; // rotation matrix row 0, col 1
public double r02; // rotation matrix row 0, col 2
public double r10; // rotation matrix row 1, col 0
public double r11; // rotation matrix row 1, col 1
public double r12; // rotation matrix row 1, col 2
public double r20; // rotation matrix row 2, col 0
public double r21; // rotation matrix row 2, col 1
public double r22; // rotation matrix row 2, col 2
public double fx; // camera intrinsics focal length x
public double fy; // camera intrinsics focal length y
public double ox; // camera intrinsics principal point x
public double oy; // camera intrinsics principal point y
public double latitude; // WGS84 latitude
public double longitude; // WGS84 longitude
public double altitude; // GPS elevation
public string b64; // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
}
[Serializable]
public class SDKImageResult
{
public string path;
}

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.

[Serializable]
public class SDKLocalizeRequest : SDKRequestBase
{
public double fx; // camera intrinsics focal length x
public double fy; // camera intrinsics focal length y
public double ox; // camera intrinsics principal point x
public double oy; // camera intrinsics principal point y
public string b64; // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB
public SDKMapId[] mapIds; // list of maps to localize against
}
[Serializable]
public class SDKLocalizeResult : SDKResultBase
{
public bool success;
public int map; // ID of the map if localization was successful
public float px; // x position within the map
public float py; // y position within the map
public float pz; // z position within the map
public float r00; // rotation matrix row 0, col 0
public float r01; // rotation matrix row 0, col 1
public float r02; // rotation matrix row 0, col 2
public float r10; // rotation matrix row 1, col 0
public float r11; // rotation matrix row 1, col 1
public float r12; // rotation matrix row 1, col 2
public float r20; // rotation matrix row 2, col 0
public float r21; // rotation matrix row 2, col 1
public float r22; // rotation matrix row 2, col 2
}

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.

[Serializable]
public class SDKGeoLocalizeRequest : SDKLocalizeRequest
{
public double latitude;
public double longitude;
public double radius;
}

Map coordinates in ECEF system (GPS)

ECEF request / response

[Serializable]
public class SDKEcefRequest : SDKRequestBase
{
public int id; // map ID
}
[Serializable]
public class SDKEcefResult : SDKResultBase
{
public double[] ecef; // ECEF coordinates
}

Delete Map

Delete map request / response

[Serializable]
public class SDKDeleteMapRequest : SDKRequestBase
{
public int id; // map ID
}
[Serializable]
public class SDKDeleteMapResult : SDKResultBase
{
}

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.

[Serializable]
public class SDKRestoreMapImagesRequest : SDKRequestBase
{
public int id; // map ID
}
[Serializable]
public class SDKRestoreMapImagesResult : SDKResultBase
{
}

Load Constructed Map

Map request / response

[Serializable]
public class SDKMapRequest : SDKRequestBase
{
public int id; // map ID
}
[Serializable]
public class SDKMapResult
{
public string md5_al; // MD5 hash for the loaded map
public string b64; // Base64 encoded .bytes map file
}

Errors

The REST API uses the following error codes (TBD):

Error Code

Meaning

400

Bad Request -- Your request is invalid.