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/v1/ubln"
}
);

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": "2024-04-12T10:43:05.078Z",
"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": "2024-04-12T10:43:05.078Z",
"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": "2024-04-12T10:43:05.078Z",
"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": "2024-04-12T10:43:05.078Z",
"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).

UNO

Example JSON structure:

[
{
"$hex": {
"data": [
1,
2,
3,
4
],
"separator": ":",
"uppercase": "boolean",
"length": 6
}
},
{
"$ibeacon": "uuid"
},
{
"$parseHex": "0x1337"
},
{
"$serviceData": {
"uuid": "00c922a3-219b-42ba-8b37-5134c0a1d000",
"offset": "integer",
"size": "integer"
}
},
{
"$mfData": {
"id": 1234,
"offset": "integer",
"size": "integer"
}
},
{
"$eq": []
},
{
"$neq": []
},
{
"$lt": []
},
{
"$lte": []
},
{
"$gt": []
},
{
"$gte": []
},
{
"$and": []
},
{
"$or": []
},
{
"$concat": []
}
]

Eval

https://uno.undagrid.xyz/schema/eval.schema.json

Evaluation expression for UNO Scan Profile

Eval contains Eval $hex

Eval contains Eval $ibeacon

Eval contains Eval $parseHex

Eval contains Eval $serviceData

Eval contains Eval $mfData

Eval contains Eval $eq

Eval contains Eval $neq

Eval contains Eval $lt

Eval contains Eval $lte

Eval contains Eval $gt

Eval contains Eval $gte

Eval contains Eval $and

Eval contains Eval $or

Eval contains Eval $concat

Eval $hex

https://uno.undagrid.xyz/schema/evalhex.schema.json

Convert a byte array to a hexadecial string

Property Type Required Description Constraints
$hex object yes See Eval $hex : $hex

Eval $hex : $hex

Property Type Required Description Constraints
data array of integer yes The byte array to convert to hexadecial
maxinum: 255
separator string no Byte separator string default value: ``
uppercase boolean no Generate hexadecimal string in uppercase, this default true default value: true
length integer no

Eval $ibeacon

https://uno.undagrid.xyz/schema/evalibeacon.schema.json

Extract data from an ibeacon payload

Property Type Required Description Constraints
$ibeacon enumerated string yes possible values: uuid, major, minor

Eval $parseHex

https://uno.undagrid.xyz/schema/evalparsehex.schema.json

parse a hexadeciamal string of a byte array

Property Type Required Description Constraints
$parseHex string no String to parse. May contain separator characters as well as 0x prefix

Eval $serviceData

https://uno.undagrid.xyz/schema/evalservicedata.schema.json

Extract data from a BLE service

Property Type Required Description Constraints
$serviceData object yes See Eval $serviceData : $serviceData

Eval $serviceData : $serviceData

Property Type Required Description Constraints
uuid string no 16 or 128 bit BLE service UUID
offset integer no Byte offset of the first byte
size integer no The amount of bytes to extract

Eval $mfData

https://uno.undagrid.xyz/schema/evalmfdata.schema.json

Extract data from a BLE manufacturer data

Property Type Required Description Constraints
$mfData object yes See Eval $mfData : $mfData

Eval $mfData : $mfData

Property Type Required Description Constraints
id number no The manufacturer ID mininum: 0
maxinum: 65536
offset integer no Byte offset of the first byte
size integer no The amount of bytes to extract

Eval $eq

https://uno.undagrid.xyz/schema/evaleq.schema.json

Eval if items are equal, returns true is all array elements are euqal

Property Type Required Description Constraints
$eq array of object yes An array of eval objects to compare. minimum nr of items: 2

Eval $neq

https://uno.undagrid.xyz/schema/evalneq.schema.json

Eval if items are NOT equal, returns true is all array elements are not euqal

Property Type Required Description Constraints
$neq array of object yes An array of eval objects to compare. minimum nr of items: 2

Eval $lt

https://uno.undagrid.xyz/schema/evallt.schema.json

Eval argument 1 is less than argument 2

Property Type Required Description Constraints
$lt array of object yes An array of eval objects to compare. minimum nr of items: 2
maximum nr of items: 2

Eval $lte

https://uno.undagrid.xyz/schema/evallte.schema.json

Eval argument 1 is less than or equal to argument 2

Property Type Required Description Constraints
$lte array of object yes An array of eval objects to compare. minimum nr of items: 2
maximum nr of items: 2

Eval $gt

https://uno.undagrid.xyz/schema/evalgt.schema.json

Eval argument 1 is greater than argument 2

Property Type Required Description Constraints
$gt array of object yes An array of eval objects to compare. minimum nr of items: 2
maximum nr of items: 2

Eval $gte

https://uno.undagrid.xyz/schema/evalgte.schema.json

Eval argument 1 is greater than or equal to argument 2

Property Type Required Description Constraints
$gte array of object yes An array of eval objects to compare. minimum nr of items: 2
maximum nr of items: 2

Eval $and

https://uno.undagrid.xyz/schema/evaland.schema.json

Eval the boolean AND of argument 1 and argument 2

Property Type Required Description Constraints
$and array of object yes An array of eval objects to compare. They need to evaluate to boolean minimum nr of items: 2
maximum nr of items: 2

Eval $or

https://uno.undagrid.xyz/schema/evalor.schema.json

Eval the boolean OR of argument 1 and argument 2

Property Type Required Description Constraints
$or array of object yes An array of eval objects to compare. They need to evaluate to boolean minimum nr of items: 2
maximum nr of items: 2

Eval $concat

https://uno.undagrid.xyz/schema/evalconcat.schema.json

Concatenates values into a string

Property Type Required Description Constraints
$concat array of object yes An array of things to concatenate. Any non-string argument will be converted to a string. minimum nr of items: 2

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!