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:

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

Solver Request : request

BLE Link

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

A link consisting of a measurement via BLE

BLE Link extends Link

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

Anchor Data

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

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

Inclination

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

An inclination value, represented by the angles to gravity

Radio Model

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

A model of the radio properties

Cell Link

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

A link consisting of a measurement via cellular technology.

Cell Link extends Link

Solver Request : request : context

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

Result

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

Result : solverMetaData

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

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

Eval $hex : $hex

Eval $ibeacon

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

Extract data from an ibeacon payload

Eval $parseHex

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

parse a hexadeciamal string of a byte array

Eval $serviceData

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

Extract data from a BLE service

Eval $serviceData : $serviceData

Eval $mfData

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

Extract data from a BLE manufacturer data

Eval $mfData : $mfData

Eval $eq

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

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

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

Eval $lt

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

Eval argument 1 is less than argument 2

Eval $lte

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

Eval argument 1 is less than or equal to argument 2

Eval $gt

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

Eval argument 1 is greater than argument 2

Eval $gte

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

Eval argument 1 is greater than or equal to argument 2

Eval $and

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

Eval the boolean AND of argument 1 and argument 2

Eval $or

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

Eval the boolean OR of argument 1 and argument 2

Eval $concat

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

Concatenates values into a string

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

The following HTTP error codes are supported"