Navigation

Introduction

Welcome to the seamless positioning API reference documentation. This documentation will guide you through the API endpoints.

Transport

All endpoints use HTTPS with https://undagrid.xyz/v1/ as the BaseAddress. You can use traditional HTTP 1.1, but also H2 or Spdy are supported.

All endpoints produce and consume JSON unless otherwise stated.

Rate limiting

Several rate limiting headers are present to show clients when they reach API limits:

Header Description
x-ratelimit-period The window in seconds within which the rate limiting is applied
x-ratelimit-limit The total amount of calls available within the window
x-ratelimit-remaining The amount of calls still available within the window
x-ratelimit-tokenconcurrentlimit The amount of concurrent calls one can do with a single authentication token

In case of non-adherence to these limits, a HTTP 429 is issued.

Also, the amount of errors is tracked. If a client makes too many errors, it may be barred from communicating to the API.

Authentication

Example creation of a keypair:

import Keypairs from "keypairs";
Keypairs.generate({ kty: "ECDSA", namedCurve: "P-256" }).then(
(pair: { public: any, private: any }) => {
(async () => {
const publicKey = await Keypairs.export({
jwk: pair.public,
format: "spki"
});
const privateKey = await Keypairs.export({
jwk: pair.private,
format: "pkcs8"
});
})();
});

See keypairs form more info

Access to the API is granted via JWT bearer token on the Authorization HTTP header.

The JWT tokens for the API you must generate by yourself. For this you’ll need to generate a RSA-2048 or ECDSA-P-256 keypair.

Send Undagrid your public key. We will store the key for you and bind it to the API endpoint. In return we will give you a key Id kid. We’re planning to add UI and API support for adding public keys to your environment at a later stage.

Example creation of JWT:

import * as jwt from "jsonwebtoken";
const token = jwt.sign(
{}, privateKey,
{
algorithm: "ES256",
expiresIn,
keyid: "kid",
audience: "https://undagrid.xyz"
}
);

See jsonwebtoken for more information

Now you can generate a JWT with your private key. Additional parameters for the JWT should include the kid as well as the audience https://undagrid.xyz. This token can then be used to access the API endpoints.

Location Request

Currently, the API consists of a single endpoint.

HTTP Request

POST {BaseAddress}/locate

The request body should contain the solver request, as described below

Example JSON structure:

{
"request": {
"batchId": "mhvXdrZT4jP5T8vBxuvm75",
"links": [
{
"ts": "2021-07-22T08:31:20.779Z",
"isMoving": "boolean",
"anchorData": {
"lat": 52.2370042,
"lon": 6.8537073,
"accuracy": 5.5,
"floor": "B1",
"height": 12.3,
"namedLocation": "foobar",
"orientation": {
"x": 90,
"y": 90,
"z": 0
},
"azimuth": 42,
"radioModel": {
"oneMeterRssi": -52,
"pathLoss": 2.7,
"backReduction": 20,
"rssiCutoff": -110,
"areaType": "URBAN"
}
},
"uri": "foobar",
"rssi": -64
},
{
"ts": "2021-07-22T08:31:20.779Z",
"isMoving": "boolean",
"anchorData": {
"lat": 52.2370042,
"lon": 6.8537073,
"accuracy": 5.5,
"floor": "B1",
"height": 12.3,
"namedLocation": "foobar",
"orientation": {
"x": 90,
"y": 90,
"z": 0
},
"azimuth": 42,
"radioModel": {
"oneMeterRssi": -52,
"pathLoss": 2.7,
"backReduction": 20,
"rssiCutoff": -110,
"areaType": "URBAN"
}
},
"cellType": "NBIOT",
"mcc": 204,
"mnc": 4,
"cellId": 26341223,
"pci": 236,
"rsrp": -101,
"rsrq": -17,
"lac": 42,
"rssi": -95,
"txPwr": 103,
"ta": 21,
"earfcn": 20400,
"isServing": true,
"antennaType": "NORMAL"
}
],
"context": {
"deviceId": "73WakrfVbNJBaAmhQtEeDv",
"profile": [
"URBAN",
"OUTDOOR"
],
"orientation": {
"x": 90,
"y": 90,
"z": 0
},
"azimuth": 42
}
},
"resultTypes": [
"POINT_RESULT"
]
}

Solver Request

https://undagrid.xyz/schema/solverrequest.schema.json

This is the primary request for the LM2M API

Property Type Required Description Constraints
request object yes See Solver Request : request
resultTypes array of enumerated string no possible values: POINT_RESULT, FIELD_RESULT minimum nr of items: 1
maximum nr of items: 3
items must be unique

Solver Request : request

Property Type Required Description Constraints
batchId string no An Id that identifies the request. LM2M does not use this internally, but will add it to the response.
links array of BLE Link and Cell Link no An array of various radio measurements.
See BLE Link
See Cell Link
minimum nr of items: 1
context object no See Solver Request : request : context

https://undagrid.xyz/schema/blelink.schema.json

A link consisting of a measurement via BLE

BLE Link extends Link

Property Type Required Description Constraints
uri string no The URI of the BLE link
rssi number no The signal strength of the link mininum: -160
maxinum: 10

https://undagrid.xyz/schema/link.schema.json

A link represents a measurement from a reference point to an anchor. All links derive from this

Property Type Required Description Constraints
ts string no Time and date of when the measurement was made ISO formated date
isMoving boolean no Was the object moving while making the measurement
anchorData no See anchorData

Anchor Data

https://undagrid.xyz/schema/anchordata.schema.json

This is basic anchor information like location, orientation and radio properties.

Property Type Required Description Constraints
lat number yes The latitude in degrees mininum: -90
maxinum: 90
lon number yes The longitude in degrees mininum: -180
maxinum: 180
accuracy number no The horizontal accuracy of the anchor position in meters
floor string no An identification of the floor
height number no the height from local ground level in meters maxinum: 10000
namedLocation string no A name given to the location
orientation no See orientation
azimuth number no The orientation of the anchor, where 0 is north, in clockwise direction mininum: 0
maxinum: 360
radioModel no See radioModel

Inclination

https://undagrid.xyz/schema/inclination.schema.json

An inclination value, represented by the angles to gravity

Property Type Required Description Constraints
x number yes X-axis angle to gravity mininum: 0
maxinum: 360
y number yes Y-axis angle to gravity mininum: 0
maxinum: 360
z number yes Z-axis angle to gravity mininum: 0
maxinum: 360

Radio Model

https://undagrid.xyz/schema/radiomodel.schema.json

A model of the radio properties

Property Type Required Description Constraints
oneMeterRssi number no Measured rssi at 1m distance mininum: -130
maxinum: 20
pathLoss number no The pathloss parameter mininum: 0
backReduction number no Reduction of the backlobe in dB mininum: -20
maxinum: 20
rssiCutoff number no Lowest rssi value to use this anchor mininum: -130
maxinum: 20
areaType enumerated string no Type description of the area the anchor is in possible values: RURAL, URBAN, OUTDOOR, INDOOR

https://undagrid.xyz/schema/celllink.schema.json

A link consisting of a measurement via cellular technology.

Cell Link extends Link

Property Type Required Description Constraints
cellType enumerated string no The type of cellular network. Currently only LTEM and NBIOT are supported possible values: LTEM, NBIOT
mcc number no The mobile country code mininum: 0
maxinum: 1000
mnc number no The mobile network code mininum: 0
maxinum: 100
cellId number no The mobile cell Id
pci number no The physical cell Id
rsrp number no The RSRP value mininum: -160
maxinum: 20
rsrq number no The RSRQ value mininum: -30
maxinum: 20
lac number no Local area identity code
rssi number no The signal strength value mininum: -160
maxinum: 20
txPwr number no Cell tower TX power in cB (centiBell) mininum: 0
maxinum: 1000
ta number no The cell tower timing advance value mininum: 0
maxinum: 80
earfcn number no The earfcn value
isServing boolean no To indicate that this is a serving cell
antennaType enumerated string no To indicate the type of cell possible values: NORMAL, PICO
additionalProperties no

Solver Request : request : context

Property Type Required Description Constraints
deviceId string no
profile array of enumerated string no A profile can be supplied to better help the engine understand the context of the subject. Supplying this information if available can greatly improve location accuracy.
possible values: RURAL, URBAN, OUTDOOR, INDOOR, PEDESTRIAN, CAR, BIKE, TRAIN
items must be unique
orientation no The orientation of the device. In case more detailed information of the radio model is present, this will help increase location accuracy.
See orientation
azimuth number no The orientation of the device, where 0 is north, in clockwise direction mininum: 0
maxinum: 360

Query Parameters

none

Returns

The result an array of results in the form of PointResult or a FieldResult

Example JSON structure:

{
"solverMetaData": {
"name": "foobar",
"ts": "2021-07-22T08:31:20.779Z",
"information": "foobar",
"procTimeMs": 42
},
"type": "POINT_RESULT",
"lat": 42,
"lon": 42,
"accuracy": 42,
"azimuth": 42,
"floor": "foobar",
"height": 42,
"altitude": 42,
"namedLocation": "foobar"
}

Point Result

https://undagrid.xyz/schema/pointresult.schema.json

Point Result extends Result

Property Type Required Description Constraints
type enumerated string no possible values: POINT_RESULT
lat number no The latitude in degrees mininum: 0
maxinum: 90
lon number no The longitude in degrees mininum: -180
maxinum: 180
accuracy number no The horizontal accuracy in meters mininum: 0
azimuth number no The orientation of the device, where 0 is north, in clockwise direction mininum: 0
maxinum: 360
floor string no An identification of the floor
height number no the height from local ground level in meters maxinum: 10000
altitude number no the altitude from sea level in meters maxinum: 10000
namedLocation string no A name given to the location

Result

https://undagrid.xyz/schema/result.schema.json

Property Type Required Description Constraints
solverMetaData object yes See Result : solverMetaData

Result : solverMetaData

Property Type Required Description Constraints
name string yes Name of the solver
ts string yes Date and time of the solver response ISO formated date
information string no Additional information about the solver
procTimeMs number yes Processing time spend on the solver

Example JSON structure:

{
"solverMetaData": {
"name": "foobar",
"ts": "2021-07-22T08:31:20.779Z",
"information": "foobar",
"procTimeMs": 42
},
"type": "FIELD_RESULT",
"field": {}
}

Field Result

https://undagrid.xyz/schema/fieldresult.schema.json

A field result represents a geographical probability area. This is a more precise representation of a possible location than a point.

Field Result extends Result

Property Type Required Description Constraints
type enumerated string yes possible values: FIELD_RESULT
field object no A GeoJson multipolygon representing the field(s).

Errors

The API can response with an error. Any HTTP status code other than 200 is an error.

Example JSON structure:

{
"status": "ERROR",
"message": "Something went wrong!",
"details": "Could not resolve location due to .."
}

Error

https://undagrid.xyz/schema/error.schema.json

API error

Property Type Required Description Constraints
status enumerated string yes Always says “ERROR” possible values: ERROR
message string yes A human readable short description of the error
details any no A longer explanation of the error. Often this is a string, but it could also be a more complex data structure

The following HTTP error codes are supported"

Error Code Meaning
400 Bad Request – Your request is invalid
401 Unauthorized – Your API key is wrong
403 Forbidden – No access to the API
404 Not Found – Location could not be found
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later
501 Not Implemented – This functionality is not yet implemented
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later
504 Gateway Timeout – Request timed out. Try again later
Beta!