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 |
BLE Link
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 |
Link
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 |
Cell Link
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 |