Knowledgebase

Geolocation API Primitives (API v1)

Traxmate LoRa Edge Cloud

The Traxmate LoRa Edge Cloud implements the Geolocation API as described below. The base URL for all calls to the cloud geolocation service is done to: lw.traxmate.io 

For example: lw.traxmate.io/api/v1/solve/gnss_lora_edge_singleframe

Geolocation API Primitives

The Geolocation API Primitives provide access to stand-alone geolocation solvers:

  • The Geolocation LoRa Edge GNSS API allows requesting location estimates based on GNSS scan results from LoRa Edge™ transceivers.

  • The Geolocation LoRa® API allows to query the location of devices based on observations of radio meta data information (TOA or RSSI/SNR)

The client is responsible to collect the necessary input data which might include – dependent on the algorithm – querying gateway positions, collecting network server specific radio metadata and parsing of end device radio messages to collect Wi-Fi and GNSS scans. All invocations are state less and no device state is kept and maintained by the service between API invocations.

Without state and the support for the Modem protocols, the Geolocation API Primitives lack the following functionality:

  • Seamless Almanac updates over-the-air for GNSS positioning.

  • Device clock synchronization for accurate GNSS positioning.

  • Assistance position injection for more successful GNSS positioning.

  • Device state management for keeping the Almanac state up to date.

  • Advanced Transport Services for transferring Geolocation scans or custom application-specific data to the Cloud Service.

It is thus highly recommended to rely on the Modem protocol and Modem Service API for the efficient utilization of the geolocation features of the LoRa Edge platform. For more information, please refer to the Section LoRa Edge Platform.

Geolocation LoRa Edge GNSS API

Introduction

The Geolocation LoRa Edge GNSS API allows requesting location estimates based on GNSS scan results from LoRa Edge transceivers.

Location estimates are computed based on the information contained in the GNSS scan result messages (NAV messages) originating from a LoRa Edge transceiver. Further details on how to execute a GNSS scan on a LoRa Edge transceiver are provided in the individual transceivers User Manual.

  • /api/v1/solve/gnss_lora_edge_singleframe: Use the LoRa Edge Single Frame GNSS Solver endpoint for calculating location estimates from single-scan or dual-scan GNSS capture data contained in a single NAV message.
  • /api/v1/solve/gnss_lora_edge_multiframe: If multiple NAV messages are available from GNSS scans at a static position, the LoRa Edge Multi-Frame GNSS Solver endpoint can combine these measurements into a more precise location estimate.

Note: For consistency reason, the v3 GNSS Geolocation API of the former stand alone system has been moved into the v1 namespace. The v3 API endpoints are available but deprecated. See also Legacy GLS Endpoints.

Choosing gnss_capture_time

The singleframe and multiframe GNSS solver APIs allow to specify the time of the submitted GNSS scan result using the gnss_capture_time parameter. The value of this parameter is expressed in GPS time as the number of seconds passed since 00:00 UTC (midnight) of January 5th to 6th 1980, without leap seconds. If not specified, gnss_capture_time is assumed to be the local server time at the moment the request is processed.

Note: A good choice for the value of gnss_capture_time is the reception time of the GNSS scan message by the network.

In general, it is good practice, to keep this value within 1-2 minutes accuracy. For values which deviate from the true capture time by more than 6 days, the GNSS scan message will not be usable by the solver.

If the gnss_capture_time is known with high precision (up to a few seconds of error), this information can be used to reject outliers. Please consult the next paragraph for more information.

Choosing gnss_capture_time_accuracy

The optional gnss_capture_time_accuracy parameter is expressed in seconds and specifies the maximum error of the capture time estimate from the solver relative to the initial guess. This value is used to check the plausibility of the position solution. If not specified, a value of 300 seconds is assumed.

Note: In most cases it is safe to omit the gnss_capture_time_accuracy parameter in your request. If the application has knowledge of the GNSS scan time with a precision of up to a few seconds, this information can be used to increase the location estimation performance.

The initial capture time guess in most cases is taken from the GNSS scan message directly. The GNSS scan message contains the device-local time at the moment the GNSS scan was performed with a resolution of 16 seconds.

In some cases, the GNSS scan time may be known to the application with a precision of up to a few seconds. For example, this can be the case when the GNSS scan is triggered by an external event which occurs at known points in time. Under such conditions, the application has the chance to increase the location estimation performance by providing the precise time of the capture in the gnss_capture_time parameter and specifying the expected timing error in the gnss_capture_time_accuracy parameter.

Choosing gnss_assist_position

The assistance position is expressed as latitude and longitude coordinates in degrees inside the WGS84 reference frame. This position is used as a starting point for the iterative position solver.

In most cases, the last known position of the device can be used as the assistance position of the subsequent request. This approach assumes that the device does not move more than 150 km between subsequent requests. In situations where this constrained cannot be met, the TDOA-based location estimation of the uplink message or application-level contextual location information (e.g. known city of deployment) may be used as an assistance position.

LoRa Edge Single Frame GNSS Solver

POST /api/v1/solve/gnss_lora_edge_singleframe

Requests a location estimate for a single on-chip GNSS scan result.

Request Headers

Request Body:

The request body contains a JSON object with the navigation message in hexadecimal notation as well as optional parameters for the position solver.

{
  "payload":                    HEX,            // Required. GNSS scan result payload (NAV message) in hexadecimal notation
  "gnss_capture_time":          FLOAT,          // Optional. capture time estimate, GPST
  "gnss_capture_time_accuracy": FLOAT,          // Optional. capture time accuracy, seconds, default: 300
  "gnss_assist_position":       [FLOAT, FLOAT], // Optional. assistance position WGS84, (latitude, longitude) [deg]
  "gnss_assist_altitude":       FLOAT,          // Optional. assistance altitude, (above WGS84 reference ellipsoid) [m]
  "gnss_use_2D_solver":         BOOL            // Optional. force 2D solve, "gnss_assist_altitude" mandatory
}
  • payload: Required. GNSS scan result payload (single- or dual-scan) in hexadecimal notation. The destination byte of the LoRa Edge GNSS API is not part of the payload and must be stripped before submission.

  • gnss_capture_time: Optional. An estimate of the time when the GNSS observation has been taken, in seconds GPST. If no gnss_capture_time is given, then local server time is used. See Section Choosing gnss_capture_time.

  • gnss_capture_time_accuracy: Optional. Capture-time estimate accuracy, in seconds. This value is used to check the plausibility of the position solution. Position solutions, where the calculated capture time deviates from the estimated capture time by more than gnss_capture_time_accuracy, will be rejected. If this value is below 16, the capture time encoded in the binary payload is ignored and gnss_capture_time is used as the initial estimate for the iterative position solver. Default value: 300 seconds. See Section Choosing gnss_capture_time_accuracy.

  • gnss_assist_position: Optional. Assistance position as latitude and longitude coordinates in degrees inside the WGS84 reference frame. This position is used as a starting point for the iterative position solver. Examples: [55.341414, 11.030974][37.819222, -122.478521][-33.852482, 151.210686]

  • gnss_assist_altitude: Optional. Precise altitude of the device at capture time, in meters above the WGS84 reference ellipsoid. Required if gnss_use_2D_solver is True.

  • gnss_use_2D_solver: If True, the value of gnss_assist_altitude is used as a fixed solution coordinate, reducing the required positioning algorithm to a 2D solution problem. gnss_assist_altitude should have an accuracy of 10 meters or better. Otherwise, the position solution quality is degraded.

Note

Timestamps in GPS time (GPST) are seconds passed since 00:00 UTC (midnight) of January 5th to 6th 1980, without leap seconds.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the response contains a result object. The errors field denotes a non-empty array of error messages in case errors are encountered. Warnings are reported in the warnings field.

{
  "result":   POSITION_SOLUTION | null,   // Optional. Position solution object or null
  "errors":   STRING[], // Optional. Array of error messages
  "warnings": STRING[]  // Optional. Array of warning messages
}

with

POSITION_SOLUTION = {
  "ecef":             [FLOAT, FLOAT, FLOAT],  // Required. Position solution in ECEF cartesian coordinates [m]
  "llh":              [FLOAT, FLOAT, FLOAT],  // Required. Position solution in WGS84 LLH coordinates [deg]
  "gdop":             FLOAT,                  // Required. Geometric dilution of precision
  "accuracy":         FLOAT,                  // Required. Estimated position solution accuracy in meters
  "capture_time_gps": FLOAT,                  // Required. Estimated time of the capture in GPST
}
  • result: Optional. If set, a position solution object with the estimated location. If null, no estimation could be computed.

  • errors: Optional. If set, an array of error messages.

  • warnings: Optional. If set, an array of warning messages.

  • ecef: Position solution in ECEF cartesian coordinates [m].

  • llh: Position solution in WGS84 LLH coordinates [deg].

  • gdop: Geometric dilution of precision.

  • accuracy: Estimated position solution accuracy. Values > 0.0 are in meters. Value ‘0.0’ means an accuracy estimate is not available.

  • capture_time_gps: Estimated time of the capture [GPST].

LoRa Edge Multi-Frame GNSS Solver

POST /api/v1/solve/gnss_lora_edge_multiframe

Request a location estimate for a list of GNSS scan result originating from a static position.

Request Headers

Request Body:

The request body contains a JSON object with a list of capture information entries. Optional timing parameters are set for each capture. Optional position solver parameters are set in the top-level request object.

{
  "captures":                   [ CAPTURE, .. ],   // Required. List of CAPTURE objects
  "gnss_capture_time_accuracy": FLOAT              // Optional. Capture time accuracy, in seconds.
  "gnss_assist_position":       [FLOAT, FLOAT],    // Optional. Assistance position WGS84, (latitude, longitude) [deg]
  "gnss_assist_altitude":       FLOAT              // Optional. assistance altitude, (above WGS84 reference ellipsoid) [m]
  "gnss_use_2D_solver":         BOOL,              // Optional. Force 2D solve, "gnss_assist_altitude" mandatory
}

with

CAPTURE = {
  "payload":                    HEX,   // Required. GNSS scan result payload (NAV message) in hexadecimal notation
  "gnss_capture_time":          FLOAT, // Optional. Capture time estimate, GPST.
}
  • captures: Required. List of CAPTURE objects. Possible lengths: 2,4,8,16,32.

  • gnss_assist_position: Optional. Assistance position as latitude and longitude coordinates in degrees inside the WGS84 reference frame. This position is used as a starting point for the iterative position solver. Examples: [55.341414, 11.030974][37.819222, -122.478521][-33.852482, 151.210686]

  • gnss_assist_altitude: Optional, Precise altitude of the device at capture time, in meters above the WGS84 reference ellipsoid. Required if gnss_use_2D_solver is True.

  • gnss_use_2D_solver: If True, the value of gnss_assist_altitude is used as a fixed solution coordinate, reducing the required positioning algorithm to a 2D solution problem. gnss_assist_altitude should have an accuracy of 10 meters or better. Otherwise, the position solution quality is degraded.

  • payload: Required. GNSS scan result payload (single- or dual-scan) in hexadecimal notation. The destination byte of the LoRa Edge GNSS API is not part of the payload and must be stripped before submission.

  • gnss_capture_time: Optional. An estimate of the time when the GNSS observation has been taken, in seconds GPST. If no gnss_capture_time is given, then local server time is used as an initial estimate for the capture time. See Section Choosing gnss_capture_time.

  • gnss_capture_time_accuracy: Optional. Capturetime estimate accuracy, in seconds. This value is used to check the plausibility of the position solution. Position solutions, where the calculated capture time deviates from the estimated capture time by more than gnss_capture_time_accuracy, will be rejected. If this value is below 16, the capture time encoded in the binary payload is ignored and gnss_capture_time is used as the initial estimate for the iterative position solver. Default value: 300 seconds. See Section Choosing gnss_capture_time_accuracy.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. Warnings will be reported in the warnings field.

{
  "result":   POSITION_SOLUTION,   // Optional. Position solution object or null
  "errors":   STRING[]  // Optional. Array of error messages
  "warnings": STRING[]  // Optional. Array of warning messages
}

with

POSITION_SOLUTION = {
  "ecef":             [FLOAT, FLOAT, FLOAT],  // Required. Position solution in ECEF cartesian coordinates [m]
  "llh":              [FLOAT, FLOAT, FLOAT],  // Required. Position solution in WGS84 LLH coordinates [deg]
  "gdop":             FLOAT,                  // Required. Geometric dilution of precision
  "accuracy":         FLOAT,                  // Required. Estimated position solution accuracy in meters
  "capture_time_gps": [ FLOAT|NULL , ..],     // Required. Estimated times of the submitted captures in GPST
}
  • result: Optional. If set, a position solution object with the estimated location. If null, no estimation could be computed.

  • errors: Optional. If set, an array of error messages.

  • warnings: Optional. If set, an array of warning messages.

  • ecef: Position solution in ECEF cartesian coordinates (m).

  • llh: Position solution in WGS84 LLH coordinates (deg).

  • gdop: Geometric dilution of precision (m).

  • accuracy: Estimated position solution accuracy (m).

  • capture_time_gps: List of estimated time of the captures in (GPST). The length of the list corresponds to the length of the captures list in the request. If the capture time could not be computed for an individual capture, the corresponding element in capture_time_gps is set to null.

Geolocation LoRa® API

Introduction

The Geolocation LoRa® API offers TOA- and RSSI- based geolocation.

The API is based on the v2 and v3 API of the former “LoRa Cloud Geolocation Service”. For consistency reason, these APIs have been merged into the v1 API namespace of the Modem & Geolocation Service. To ease migration, the original v2 and v3 APIs endpoints are available but deprecated, see Legacy GLS Endpoints.

The Geolocation v1 API partially implements the v2 COLLOS (Collaborative Location Service) API. In particular, the following subset of operations is supported:

  • /api/v1/solve/rssi: Calculates a location for a device according to received signal strength indicator (RSSI) data.

  • /api/v1/solve/rssiMultiframe: Calculates a location for a device according to RSSI data captured over multiple LoRa® frames (uplinks). All frames are assumed to have been transmitted from the same location and will result in a single location estimate.

  • /api/v1/solve/tdoa: Calculates a location for a device according to RSSI data combined with high-resolution time of arrival (TOA) data.

  • /api/v1/solve/tdoaMultiframe: Calculates a location for a device according to RSSI and TOA data captured over multiple LoRa® frames (uplinks). All frames are assumed to have been transmitted from the same location and will result in a single location estimate.

  • /api/v1/solve/loraWifi: Calculates a location for a device based on a combination of the TOA technique described above plus any Wi-Fi access point data contained in the payload of the LoRa® uplink combined. The algorithms will return a single location estimate.

The Geolocation v1 API implements the v3 API of the former stand alone Geolocation Service:

  • /api/v1/solve/singleframe: Calculates a location for a device based on RSSI, TOA or both. The algorithm is selected by API parameter. A single location estimate is computed.

  • /api/v1/solve/multiframe: Calculates a location based on multiple frames transmitted by a single device. The alogorithm is selected by parameter. A single location estimate is computed.

  • /api/v1/solve/singleframes: Allow bundling of multiple “singleframe” requests, i.e. multiple single frames as described above. These may be multiple transmissions from a single device in multiple locations or a single transmission from multiple devices. A location estimation per frame is computed.

  • /api/v1/solve/multiframe: Allow bundling of multiple “multiframe” requests, i.e. multiple multi-frames as described above. These may be bundles of uplinks received by multiple devices in static locations, or bundles of frames received from a device, including moves and stops. A location estimation per multi-frame is computed

Note: The API does not support the Gateway Management functions of the original COLLOS API. Clients cannot upload gateway information to the server and then reference it in later calls. Rather, customers must provide the location information of gateways in each invocation.

Note: The API does not evaluate the parameter encryptedToa. Encrypted TOA timestamps must be decrypted before invoking the Geolocation Service.

Legacy GLS API Endpoints

The following API endpoints exist to ease migration from the former “LoRaCloud Geolocation Service”.

They are deprecated and will be removed in the future.

Note: The authentication token must be presented in the header field “Authorization” in all cases. The field “Ocp-Apim-Subscription-Key” used by the former LoRaCloud GLS API is now unsupported for all API endpoints.

Please refer to the Migration Guide for more details.

Gateway and Frame Input Filtering

The specification strictly identifies the expected and supported fields in API requests. The Geolocation Service filters out gateway and frame information that is not valid and tries to compute an estimate from the remaining information. The filtered input data is signaled in the warning field of the result.

The recommendation for new clients is to verify and filter the data from gateways before they forward requests to the Geolocation Service. To support older clients, the current implementation filters out gateway and frame information that is not valid, and tries to compute an estimate from the remaining information. The filtered input data is signaled in the warning field of the result.

The Geolocation Service also filters out gateway and frame input data in the following cases:

  • Gateway: A gateway is filtered if gatewayId is empty or not specified, if latitude is null or not valid, or if longitude is empty or not valid. If altitude is null or omitted, 0 is used.

  • Frame: An frame is filtered if its gateway field is not valid, its rssi field is not valid, or its snr field is not valid. If antenna is null, 0 is used. If TDOA is null, 0 is set.

RSSI Singleframe Request

POST /api/v1/solve/rssi

Calculates the location of a device according to received signal strength indicator (RSSI) data. In contrast to the COLLOS API, the location information of gateways must be included in the call.

Request Headers

Request Body:

The request body stores a JSON object which includes the field lorawan. The lorawan field carries an array of uplink objects. Each uplink object contains the metadata from the message that was received by a gateway antenna. The metadata includes RSSI, SNR and antenna location information.

{
   "lorawan":  ARRAY  // Required. Array of Uplink RSSI objects.
}

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the RSSI request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those if the array is not null.

{
   "result":   OBJECT,   // Optional. Location result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional. If set, this is an instance of v2LocationResult.

  • errors: Optional. If not empty, an array of error messages.

  • warnings: Optional. If not empty, an array of warning messages.

Example Request:

POST /api/v1/solve/rssi HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json

{
    "lorawan": [{
            "gatewayId": "00-00-E4-77-6B-00-1A-5D",
            "antennaId": 0,
            "rssi": -86.0,
            "snr": 15.0,
            "antennaLocation": {
                "latitude": 46.98886,
                "longitude": 6.91287,
                "altitude": 513
            }
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1A-5D",
            "antennaId": 1,
            "rssi": -87.0,
            "snr": 15.0,
            "antennaLocation": {
                "latitude": 46.98886,
                "longitude": 6.91287,
                "altitude": 513
            }
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1A-97",
            "antennaId": 0,
            "rssi": -89.0,
            "snr": 15.0,
            "antennaLocation": {
                "latitude": 46.983753,
                "longitude": 6.906008,
                "altitude": 479
            }
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1A-97",
            "antennaId": 1,
            "rssi": -89.0,
            "snr": 10.0,
            "antennaLocation": {
                "latitude": 46.983753,
                "longitude": 6.906008,
                "altitude": 479
            }
        }
    ]
}

Example Response:

{
   "result":{
      "latitude": 6.909439,
      "longitude": 6.909439,
      "altitude": 0.0,
      "accuracy": 269,
      "algorithmType": "Rssi",
      "numberOfGatewaysReceived": 2,
      "numberOfGatewaysUsed": 2
   },
   "warnings":[],
   "errors":[]
}

TDOA Singleframe Request

POST /api/v1/solve/tdoa

Calculates the location of a device according to RSSI data combined with time of arrival (TOA) data. The time of arrival is in nano-seconds and is only supported by LoRa® gateways with the appropriate high-resolution time-stamping features. In contrast to the COLLOS API, the location information of gateways must be included in the call.

Note: Also in contrast to COLLOS, the call does not support encrypted timestamps in encryptedToa fields.

Request Headers

Request Body:

The request body stores a JSON object which contains the field lorawan. The lorawan field carries an array of uplink objects, i.e. the frame information. Each uplink object contains the metadata required for the message to be received by a gateway anteanna. This metadata incldues the TDOA timestamp, RSSI, SNR and antenna location information.

{
   "lorawan":  ARRAY  // Required. The frame, an array of Uplink TDOA objects.
}

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the TDOA request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those if the array is not null.

{
   "result":   OBJECT,   // Optional. Location result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional, if set, a v2LocationResult instance.

  • errors: Optional. If not empty, an array of error messages.

  • warnings: Optional. If not empty, an array of warning messages.

Example Request:

POST /api/v1/solve/tdoa HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
  "lorawan": [
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 0,
        "rssi": -86.0,
        "snr": 15.0,
        "toa": 611795075,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 1,
        "rssi": -87.0,
        "snr": 15.0,
        "toa": 611795149,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 0,
        "rssi": -89.0,
        "snr": 15.0,
        "toa": 611794074,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 1,
        "rssi": -89.0,
        "snr": 10.0,
        "toa": 611793747,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    }]
  }
}

Example Response:

{
   "result":{
      "latitude": 6.909439,
      "longitude": 6.909439,
      "altitude": 0.0,
      "accuracy": 269,
      "algorithmType": "Tdoa",
      "numberOfGatewaysReceived": 2,
      "numberOfGatewaysUsed": 2
   },
   "warnings":[],
   "errors":[]
}

RSSI Multiframe Request

POST /api/v1/solve/rssiMultiframe

Calculates a location for a device according to the received signal strength indicator (RSSI) data captured from multiple LoRa® frames (uplinks). In contrast to the COLLOS API, the location information of gateways must be included in the call.

The call takes a sequence of single frames (consisting of multiple uplink objects), that are typically received by the gateways within a short time frame. These frames are assumed to be transmitted by the device in the same location.

The result is a single location estimate. Using the sequence of radio frames for a single estimate allows for estimating the device’s location with higher accuracy than the single-frame alternative. The multi-frame technique also combines all the available data into a single calculation, resulting in a location estimate that is generally more accurate than averaging multiple locations calculated from several single frames.

Request Headers

Request Body:

The request body stores a JSON object which contains a field, lorawan. This field carries an array of frames. Each frame consists of an array of uplink instances, as is the case in the RSSI single-frame call.

{
  "lorawan":  [    // Required. An array of frame objects.
    ARRAY          // Required. A frame, an array of Uplink RSSI objects.
  ]
}
  • lorawan: Required. array of array of v2UplinkRssi objects.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the rssiMultiframe request responds with a result. The errors field denotes a non-empty array of error messages to display if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those, if the array is not null.

{
   "result":   OBJECT,   // Optional. Location result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional. If set, this is an instance of v2LocationResult.

  • errors: Optional. If not empty, an array of error messages.

  • warnings: Optional. If not empty, an array of warning messages.

Example Request:

POST /api/v1/solve/rssiMultiframe HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
 "lorawan": [
 [
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-5D",
      "antennaId": 0,
      "rssi": -86.0,
      "snr": 15.0,
      "antennaLocation": {
          "latitude":46.98886,
          "longitude":6.91287,
          "altitude":513
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-5D",
      "antennaId": 1,
      "rssi": -87.0,
      "snr": 15.0,
      "antennaLocation": {
          "latitude":46.98886,
          "longitude":6.91287,
          "altitude":513
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-97",
      "antennaId": 0,
      "rssi": -89.0,
      "snr": 15.0,
      "antennaLocation": {
          "latitude":46.983753,
          "longitude":6.906008,
          "altitude":479
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-97",
      "antennaId": 1,
      "rssi": -89.0,
      "snr": 10.0,
      "antennaLocation": {
          "latitude":46.983753,
          "longitude":6.906008,
          "altitude":479
      }
  }
 ],
 [
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-5D",
      "antennaId": 0,
      "rssi": -88.0,
      "snr": 15.0,
      "antennaLocation": {
          "latitude":46.98886,
          "longitude":6.91287,
          "altitude":513
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-5D",
      "antennaId": 1,
      "rssi": -87.0,
      "snr": 14.5,
      "antennaLocation": {
          "latitude":46.98886,
          "longitude":6.91287,
          "altitude":513
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-97",
      "antennaId": 0,
      "rssi": -91.0,
      "snr": 14.8,
      "antennaLocation": {
          "latitude":46.983753,
          "longitude":6.906008,
          "altitude":479
      }
  },
  {
      "gatewayId": "00-00-E4-77-6B-00-1A-97",
      "antennaId": 1,
      "rssi": -84.0,
      "snr": 11.0,
      "antennaLocation": {
          "latitude":46.983753,
          "longitude":6.906008,
          "altitude":479
      }
  }
 ]
 ]
}

Example Response:

{
   "result":{
      "latitude": 6.909439,
      "longitude": 6.909439,
      "altitude": 0.0,
      "accuracy": 269,
      "algorithmType": "Rssi",
      "numberOfGatewaysReceived": 2,
      "numberOfGatewaysUsed": 2
   },
   "warnings":[],
   "errors":[]
}

TDOA Multiframe Request

POST /api/v1/solve/tdoaMultiframe

Calculates the location of a device according to received signal strength indicator (RSSI) data, combined with the time of arrival (TOA) data that has been received from multiple LoRa® frames (uplinks). In contrast to the COLLOS API, the location information of the gateways must be included in the call.

The call takes a sequence of single frames (consisting of multiple uplink objects) that are received by the gateways, typically within a short time frame. These frames are assumed to be transmitted by devices in the same location.

The result is still a single location estimate. Using the sequence of radio frames for a single location estimate allows estimating the device location with higher accuracy than the single-frame alternative. The multi-frame technique also combines all the available data into a single calculation, resulting in a location estimate that is generally more accurate than averaging multiple locations calculated from several single frames.

Note: In contrast to COLLOS, the call does not support encrypted timestamps in encryptedToa fields.

reqheader Accept

application/json

reqheader Authorization

Required. Access token

Request Body:

The request body stores a JSON object which contains the field lorawan. This field carries an array of uplink objects, i.e. the frame information. Each uplink object contains metadata captured when the messages were received by each gateway antenna. This metadata includes the TOA timestamp, RSSI, SNR, and antenna location information.

{
  "lorawan":  [    // Required.  array of frame objects.
    ARRAY          // Required.  a frame, an array of Uplink TDOA objects.
  ]
}
  • lorawan: Required. array of array of v2UplinkTdoa objects.

Response:

statuscode 200

No errors

statuscode 401

Authentication failed

statuscode 400

No estimation could be computed or error during execution

statuscode 429

Rate limit exceeded

resheader Content-Type

application/json

Response JSON:

If the request executes successfully, the tdoaMultiframe request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those if the array is not null.

{
   "result":   OBJECT,   // Optional. Location result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional. If set, this is an instance of v2LocationResult.

  • errors: Optional. If not empty, an array of error messages.

  • warnings: Optional. If not empty, an array of warning messages.

Example Request:

POST /api/v1/solve/tdoaMultiframe HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
 "lorawan": [
 [
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 0,
        "rssi": -86.0,
        "snr": 15.0,
        "toa": 611795075,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 1,
        "rssi": -87.0,
        "snr": 15.0,
        "toa": 611795149,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 0,
        "rssi": -89.0,
        "snr": 15.0,
        "toa": 611794074,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 1,
        "rssi": -89.0,
        "snr": 10.0,
        "toa": 611793747,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    }
 ],
 [
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 0,
        "rssi": -89.0,
        "snr": 14.5,
        "toa": 611795079,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 1,
        "rssi": -94.0,
        "snr": 14.5,
        "toa": 611795152,
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 0,
        "rssi": -82.0,
        "snr": 15.5,
        "toa": 611794999,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 1,
        "rssi": -91.0,
        "snr": 12.0,
        "toa": 611793990,
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    }
 ]
 ]
}

Example Response:

{
   "result":{
      "latitude": 6.909439,
      "longitude": 6.909439,
      "altitude": 0.0,
      "accuracy": 269,
      "algorithmType": "Rssi",
      "numberOfGatewaysReceived": 2,
      "numberOfGatewaysUsed": 2
   },
   "warnings":[],
   "errors":[]
}

Wi-Fi/TDOA Singleframe Request

POST /api/v1/solve/loraWifi

Retrieves the estimated device location based on Wi-Fi and LoRa® technologies. Initially, the device location is estimated based on the Wi-Fi access points that are included. If this estimate is valid, an estimate is returned. Otherwise, the device’s location is estimated based on LoRa®, by passing the included time difference of arrival (TDOA) and/or received signal strength indicator (RSSI) metadata to the algorithms that are included with the TDOA and RSSI endpoints. A single location estimate is returned.

Request Headers

Request Body:

The request body stores a JSON object with the lorawan field. This field points to an array of uplinks (as in case of /api/v1/solve/tdoa). The field wifiAccessPoints points to an array of Wi-Fi Access Point instances with at least two elements. If fewer elements are provided, only a LoRa® based estimation is performed. The request body must contain valid LoRa® uplink information. Otherwise, the call returns with an error.

{
   "lorawan":           ARRAY,  // Required. Array of Uplink TDOA objects.
   "wifiAccessPoints":  ARRAY   // Required. Array of Wi-Fi Access Point objects.
}

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the loraWifi request responds with a result. If errors are encountered, the errors field denotes a non-empty array of error messages. If there are individual input entries that are insufficient or not valid, the warnings array will report those, if the array is not null.

{
   "result":   OBJECT,   // Optional. Location result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional. If set, a v2LocationResult instance.

  • errors: Optional. If not empty, an array of error messages.

  • warnings: Optional. If not empty, an array of warning messages.

Example Request:

POST /api/v1/solve/loraWifi HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
  "lorawan": [
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 0,
        "rssi": -86.0,
        "snr": 15.0,
        "toa": 10000,
        "encryptedToa": "",
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-5D",
        "antennaId": 1,
        "rssi": -87.0,
        "snr": 15.0,
        "toa": 5000,
        "encryptedToa": "",
        "antennaLocation": {
            "latitude":46.98886,
            "longitude":6.91287,
            "altitude":513
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 0,
        "rssi": -89.0,
        "snr": 15.0,
        "toa": 8000,
        "encryptedToa": "",
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    },
    {
        "gatewayId": "00-00-E4-77-6B-00-1A-97",
        "antennaId": 1,
        "rssi": -89.0,
        "snr": 10.0,
        "toa": 20000,
        "encryptedToa": "",
        "antennaLocation": {
            "latitude":46.983753,
            "longitude":6.906008,
            "altitude":479
        }
    }],
  "wifiAccessPoints": [
    {
            "macAddress": "00:02:01:53:8B:50",
            "signalStrength": -20
    },
    {
            "macAddress": "00:02:13:44:55:20",
            "signalStrength": -80
    }]
}

Example Response:

{
   "result":{
      "latitude": 6.909439,
      "longitude": 6.909439,
      "altitude": 0.0,
      "accuracy": 269,
      "algorithmType": "Wifi",
      "numberOfGatewaysReceived": 2,
      "numberOfGatewaysUsed": 2
   },
   "warnings":[],
   "errors":[]
}

Geolocation API JSON Formats (COLLOS)

Uplink (RSSI)

The received signal strength indicator (RSSI) and signal-to-noise ratio (SNR) information for a LoRa® frame (uplink) as received by one gateway antenna.

{
  "gatewayId":       STRING,  // Required. String label.
  "rssi":            FLOAT,   // Required. RSSI, in dBm.
  "snr":             FLOAT,   // Required. SNR, float.
  "toa",             UINT32,  // Ignored.
  "encryptedToa",    UINT32,  // Ignored.
  "antennaId":       INT,     // Required. Antenna ID.
  "antennaLocation": OBJECT   // Required. Antenna Location instance.
}
  • gatewayId: Required. String. An identifier for the gateway, e.g. MAC address or label. If absent, the entry is ignored and a warning is included in the response.

  • rssi: Required. Float. RSSI value, dBm. If absent, the entry is ignored and a warning is included in the response.

  • snr: Required. Float. SNR value. If absent, the entry is ignored and a warning is included in the response.

  • toa: Ignored.

  • encryptedToa: Ignored.

  • antennaId: Antenna ID. An integer (0 or 1). If absent or null, 0 is chosen.

  • antennaLocation: Antenna location. An instance of v2AntennaLocation.

Example:

{
    "gatewayId": "00-00-E4-77-6B-00-1A-5D",
    "antennaId": 0,
    "rssi": -86.0,
    "snr": 15.0,
    "antennaLocation": {
        "latitude":46.98886,
        "longitude":6.91287,
        "altitude":513
    }
}

Uplink (TDOA)

The time of arrival (TOA), received signal strength indicator (RSSI) and signal-to-noise ratio (SNR) information for a LoRa® frame (uplink) as received by one gateway antenna.

Note: The Geolocation Service does not accept encrypted timestamps; the API expects timestamps to be decrypted by the caller.

{
  "gatewayId":       STRING,  // Required. String label.
  "rssi":            FLOAT,   // Required. RSSI, in dBm.
  "snr":             FLOAT,   // Required. SNR, float.
  "toa",             UINT32,  // Required.  TDOA, uint.
  "encryptedToa",    UINT32,  // Ignored.
  "antennaId":       INT,     // Required. antenna id.
  "antennaLocation": OBJECT   // Required. Antenna Location instance.
}
  • gatewayId: Required. String. An identifier for the gateway, e.g. MAC address or label. If absent, the entry is ignored and a warning is included in the response.

  • rssi: Required; Float. RSSI value, dBm. If absent, the entry is ignored and a warning is included in the response.

  • snr: Required. Float. SNR value. If absent, the entry is ignored and a warning is included in the response.

  • toa: Decrypted TOA value, uint32. If absent or null, 0 is chosen (in nanoseconds since “top of second”).

  • encryptedToa: Ignored.

  • antennaid: Antenna ID. An integer (0 or 1). If absent or null, 0 is chosen.

  • antennaLocation: Antenna location. An instance of v2AntennaLocation.

Example:

{
    "gatewayId": "00-00-E4-77-6B-00-1A-5D",
    "antennaId": 0,
    "rssi": -86.0,
    "snr": 15.0,
    "toa": 611793747,
    "antennaLocation": {
        "latitude":46.98886,
        "longitude":6.91287,
        "altitude":513
    }
}

Antenna Location

The location of a gateway antenna.

{
  "latitude":  FLOAT, // Required. Latitude.
  "longitude": FLOAT, // Required. Longitude.
  "altitude":  FLOAT  // Required. Altitude.
}
  • latitude: Required. Float. Latitude. If absent, the entry is ignored and a warning is included in the response.

  • longitude: Required. Float. Longitude. If absent, the entry is ignored and a warning is included in the response.

  • altitude: Required. Float. Altitude. If absent, the entry is ignored and a warning is included in the response.

Example:

{
  "latitude":46.983753,
  "longitude":6.906008,
  "altitude":479
}

Wi-Fi Access Point

Wi-Fi access point information as received by the device and transmitted in the LoRa® payload. The device, not the LoRa® gateways, captures Wi-Fi access point information.

{
  "macAddress":      STRING, // Required. String, MAC address.
  "ssid":            STRING, // Optional. String.
  "signalStrength":  INT,    // Optional. INT. Signal strength.
  "age":             INT     // Optional. Unused.
}
  • macAddress: Required. String.

  • ssid: Optional. String.

  • signalStrength: Optional. INT.

  • age: Optional. INT. Unused.

Example:

{
  "macAddress": "00:02:01:53:8B:50",
  "signalStrength": -20
}

Location Result

A successfult result of an API location lookup.

{
  "latitude":        FLOAT,        // Required. Float. Latitude.
  "longitude":       FLOAT,        // Required. Float. Longitude.
  "altitude":        FLOAT,        // Required. Float. Altitude.
  "accuracy":        INT,          // Required. INT. Accuracy.
  "algorithmType":   STRING,       // Required. "Rssi" or "Tdoa" or "Wifi"
  "numberOfGatewaysReceived": INT, // Required. INT. Number of valid input gateways.
  "numberOfGatewaysUsed": INT      // Required. INT. Number of contributing gateways.
}
  • longitude: Required. Float. Longitude.

  • latitude: Required. Float. Latitude.

  • altitude: Required. Float. Altitude.

  • accuracy: Required. INT. Accuracy.

  • numberOfGatewaysReceived: Required. INT. Number of valid input gateways.

  • numberOfGatewaysUsed: Required. INT. Number of contributing gateways.

Singleframe Request

POST /api/v1/solve/singleframe

Requests a location estimate for a single frame with multiple uplinks (receptions). Each uplink (reception) contains received information of the frame for one antenna of a gateway with RSSI, SNR and TOA timestamp data. Gateways may receive the frame on two antennas. In this case, each one will be treated as a separate uplink.

Request Headers

Request Body:

The request body contains a JSON object with gateway locations and a frame that consists of an array of uplinks. Optionally, parameters for the location solver algorithm can be specified. By default, a location is computed based on TDOA and RSSI.

{
   "gateways": ARRAY,  // Required. Array of Gateway objects.
   "frame":    OBJECT, // Required. Frame object.
   "params":   OBJECT  // Optional. Parameters object.
}
  • gateways: Required. Array of v3Gateway objects. List of gateway decriptors.

  • frames: Required. Array of v3Frame objects.

  • params: Optional. List of v3Parameters for the solver algorithm.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the singleframe request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those, if the array is not null

{
   "result":   OBJECT,   // Optional. Location solver result or null
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages, might be empty
}
  • result: Optional. If set, this is the v3LocationSolverResult, indicating the estimated location of the device. If null, no estimation could be computed.

  • errors: Optional. If set, an array of error messages.

  • warnings: Optional. If set, an array of warning messages.

Example Request:

POST /api/v1/solve/singleframe HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
    "gateways": [
        {
            "gatewayId": "0000123456789a00",
            "latitude": 51.50119,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a01",
            "latitude": 51.51019,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a02",
            "latitude": 51.50569,
            "longitude": -0.129482,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a03",
            "latitude": 51.49669,
            "longitude": -0.129482,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a04",
            "latitude": 51.49219,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a05",
            "latitude": 51.49669,
            "longitude": -0.154524,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a06",
            "latitude": 51.50569,
            "longitude": -0.154524,
            "altitude": 100
        }
    ],
    "frame": [
        ["0000123456789a00", 0, 256477, -100.0, 17.7],
        ["0000123456789a00", 1, 256433, -105.0, 13.1],
        ["0000123456789a01", 0, 258814, -116.0, 3.3],
        ["0000123456789a01", 1, 259024, -118.0, -2.7],
        ["0000123456789a02", 0, 259940, -116.0, 3.5],
        ["0000123456789a02", 1, 261383, -113.0, 0.7],
        ["0000123456789a03", 0, 259508, -119.0, -6.5],
        ["0000123456789a03", 1, 259569, -118.0, 1.6],
        ["0000123456789a04", 0, 260415, -108.0, 7.6],
        ["0000123456789a04", 1, 257252, -106.0, 7.9],
        ["0000123456789a05", 0, 256735, -97.0, 15.9],
        ["0000123456789a05", 1, 256759, -97.0, 15.6],
        ["0000123456789a06", 0, 259020, -96.0, 13.5],
        ["0000123456789a06", 1, 262640, -96.0, 15.5]
    ]
}

Example Response:

{
   "result":{
      "numUsedGateways":7,
      "HDOP":0.82,
      "algorithmType": "RssiTdoaCombined",
      "locationEst":{
         "latitude":51.499,
         "longitude":-0.147,
         "toleranceHoriz":185
      }
   },
   "warnings":[]
}

Multiframe Request

POST /api/v1/solve/multiframe

Requests a location estimate for a device using multiple frames, each with multiple uplinks. This improves the accuracy of the results for static devices over a single frame estimation because diversity is increased. Each uplink contains received information of the frame for one antenna of a gateway with received signal strength indicator (RSSI), signal-to-noise ratio (SNR) and, optionally, the time-of-arrival (TOA) timestamp.

Request Headers

Request Body:

The request body contains an object with gateway locations and an array of frames. Optionally, parameters for the location solver algorithm can be specified. By default, a location is computed based on TDOA and RSSI.

{
   "gateways": ARRAY,  // Required. Array of Gateway objects.
   "frames":   ARRAY,  // Required. Array of Frame object.
   "params":   OBJECT  // Optional. Parameters object.
}
  • gateways: Required. An array of v3Gateway objects. List of gateway decriptors.

  • frames: Required. An array of v3Frame objects.

  • params: Optional. A list of v3Parameters for the solver algorithm.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the multiframe request responds with a result. The errors field denotes a non-empty array of error messages to display if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those.

{
   "result":   OBJECT,   // Optional. Location solver result or null.
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages
}
  • result: Optional. If set, v3LocationSolverResult, a location result. If null, no estimation could be computed.

  • errors: Optional. If set, an array of error messages.

  • warnings: Optional. If set, an array of warning messages.

Example Request:

POST /api/v1/solve/multiframe HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
    "gateways": [
        {
            "gatewayId": "0000123456789a00",
            "latitude": 51.50119,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a01",
            "latitude": 51.51019,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a02",
            "latitude": 51.50569,
            "longitude": -0.129482,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a03",
            "latitude": 51.49669,
            "longitude": -0.129482,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a04",
            "latitude": 51.49219,
            "longitude": -0.142003,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a05",
            "latitude": 51.49669,
            "longitude": -0.154524,
            "altitude": 100
        },
        {
            "gatewayId": "0000123456789a06",
            "latitude": 51.50569,
            "longitude": -0.154524,
            "altitude": 100
        }
    ],
    "frames": [
        [
            ["0000123456789a00", 0, 256477, -100.0, 17.7],
            ["0000123456789a00", 1, 256433, -105.0, 13.1],
            ["0000123456789a01", 0, 258814, -116.0, 3.3],
            ["0000123456789a01", 1, 259024, -118.0, -2.7],
            ["0000123456789a02", 0, 259940, -116.0, 3.5],
            ["0000123456789a02", 1, 261383, -113.0, 0.7],
            ["0000123456789a03", 0, 259508, -119.0, -6.5],
            ["0000123456789a03", 1, 259569, -118.0, 1.6],
            ["0000123456789a04", 0, 260415, -108.0, 7.6],
            ["0000123456789a04", 1, 257252, -106.0, 7.9],
            ["0000123456789a05", 0, 256735, -97.0, 15.9],
            ["0000123456789a05", 1, 256759, -97.0, 15.6],
            ["0000123456789a06", 0, 259020, -96.0, 13.5],
            ["0000123456789a06", 1, 262640, -96.0, 15.5]
        ],
        [
            ["0000123456789a00", 0, 428994, -102.0, 12.0],
            ["0000123456789a00", 1, 428963, -95.0, 18.4],
            ["0000123456789a01", 0, 431263, -116.0, 4.6],
            ["0000123456789a01", 1, 431205, -111.0, 6.1],
            ["0000123456789a02", 0, 432594, -119.0, 4.1],
            ["0000123456789a02", 1, 434744, -115.0, 1.4],
            ["0000123456789a03", 0, 433316, -131.0, -13.8],
            ["0000123456789a03", 1, 432085, -116.0, -4.9],
            ["0000123456789a04", 0, 436371, -108.0, 6.2],
            ["0000123456789a04", 1, 436648, -104.0, 8.5],
            ["0000123456789a05", 0, 429317, -113.0, 10.0],
            ["0000123456789a05", 1, 429278, -100.0, 14.5],
            ["0000123456789a06", 0, 435562, -103.0, 14.3],
            ["0000123456789a06", 1, 435598, -112.0, 10.2]
        ],
        [
            ["0000123456789a00", 0, 216795, -103.0, 13.7],
            ["0000123456789a00", 1, 216741, -96.0, 15.1],
            ["0000123456789a01", 0, 219037, -105.0, 7.0],
            ["0000123456789a01", 1, 219168, -126.0, -1.3],
            ["0000123456789a02", 0, 221088, -117.0, 1.6],
            ["0000123456789a02", 1, 224019, -111.0, 2.6],
            ["0000123456789a03", 0, 219734, -111.0, 6.1],
            ["0000123456789a03", 1, 219872, -122.0, 0.5],
            ["0000123456789a04", 0, 222240, -106.0, 7.6],
            ["0000123456789a04", 1, 223589, -105.0, 9.6],
            ["0000123456789a05", 0, 216989, -103.0, 17.2],
            ["0000123456789a05", 1, 217032, -106.0, 14.1],
            ["0000123456789a06", 0, 218754, -103.0, 17.1],
            ["0000123456789a06", 1, 219032, -103.0, 15.0]
        ]
    ],
    "params": {"locAlgType": "TDOA_ALG", "doRssiTdoaCombine": true}
}

Example Response:

{
     "result":{
        "numUsedGateways":7,
        "HDOP":0.3,
        "algorithmType": "RssiTdoaCombined",
        "locationEst":{
           "latitude":51.50053,
           "longitude":-0.14842,
           "toleranceHoriz":92
        }
     },
     "warnings":[]
  }

Singleframes Request (Bundled)

POST /api/v1/solve/singleframes
Allows bundling of multiple single-frame requests into one HTTP request. The HTTP request carries an array of frame instances where the service returns a location estimate for each frame. If no location estimate can be calculated for that frame, a null value is returned. A location estimate is computed for each frame supplied in the array of frames. The frames can be from a single device in multiple locations or from multiple devices.

Request Headers
Accept – application/json
Authorization – Required. Access token

Request Body:

The request body contains an object with gateway locations and an array of frames. Optionally, parameters for the location solver algorithm can be specified. By default, a location is computed based on TDOA and RSSI.

{

   “gateways”: ARRAY,  // Required. Array of Gateway objects.

   “frames”:   ARRAY,  // Required. Array of Frame object (1<=n<=16).

   “params”:   OBJECT  // Optional. Parameters object.

}

  • gateways: Required. Array of v3Gateway objects. List of gateway descriptors.
  • frames: Required. Array of v3Frame objects. At least one element must be specified; a maximum of 16 elements can be included.
  • params: Optional. List of v3Parameters for the solver algorithm.

Response:

Status Codes

  • 200 OK – No errors
  • 401 Unauthorized – Authentication failed
  • 429 Too Many Requests – Rate limit exceeded

Response Headers
Content-Type – application/json

Response JSON:

If the request executes successfully, the singleframe request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those, if the array is not null.

{

   “result”:   ARRAY,    // Optional. Array of entries with location solver results or null.

   “errors”:   STRING[], // Optional. Array of error messages

   “warnings”: STRING[]  // Optional. Array of warning messages

}

  • result: Optional. If set, an array of v3LocationSolverResult or null entries. Null if no estimate could be computed for the associated input frame.
  • errors: Optional. If set, an array of error messages.
  • warnings: Optional. If set, an array of warning messages.

Example Request:

 POST /api/v1/solve/singleframes HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
 
{
    “gateways”: [
        {
            “gatewayId”: “0000123456789a00”,
            “latitude”: 51.50119,
            “longitude”: -0.142003,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a01”,
            “latitude”: 51.51019,
            “longitude”: -0.142003,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a02”,
            “latitude”: 51.50569,
            “longitude”: -0.129482,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a03”,
            “latitude”: 51.49669,
            “longitude”: -0.129482,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a04”,
            “latitude”: 51.49219,
            “longitude”: -0.142003,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a05”,
            “latitude”: 51.49669,
            “longitude”: -0.154524,
            “altitude”: 100
        },
        {
            “gatewayId”: “0000123456789a06”,
            “latitude”: 51.50569,
            “longitude”: -0.154524,
            “altitude”: 100
        }
    ],
    “frames”: [
        [
            [“0000123456789a00”, 0, 256477, -100.0, 17.7],
            [“0000123456789a00”, 1, 256433, -105.0, 13.1],
            [“0000123456789a01”, 0, 258814, -116.0, 3.3],
            [“0000123456789a01”, 1, 259024, -118.0, -2.7],
            [“0000123456789a02”, 0, 259940, -116.0, 3.5],
            [“0000123456789a02”, 1, 261383, -113.0, 0.7],
            [“0000123456789a03”, 0, 259508, -119.0, -6.5]
        ],
        [
            [“0000123456789a03”, 1, 259569, -118.0, 1.6],
            [“0000123456789a04”, 0, 260415, -108.0, 7.6],
            [“0000123456789a04”, 1, 257252, -106.0, 7.9],
            [“0000123456789a05”, 0, 256735, -97.0, 15.9],
            [“0000123456789a05”, 1, 256759, -97.0, 15.6],
            [“0000123456789a06”, 0, 259020, -96.0, 13.5],
            [“0000123456789a06”, 1, 262640, -96.0, 15.5]
        ]
    ]
}
 
Example Response:
 
{
“result”:[
{
“numUsedGateways”:4,
“HDOP”:3.24,
“algorithmType”: “RssiTdoaCombined”,
“locationEst”:{
“latitude”:51.509096,
“longitude”:-0.142713,
“toleranceHoriz”:80
}
},
{
“numUsedGateways”:4,
“HDOP”:1.39,
“algorithmType”: “RssiTdoaCombined”,
“locationEst”:{
“latitude”:51.496404,
“longitude”:-0.150144,
“toleranceHoriz”:80
}
}
],
“warnings”:[]
}
 

Multiframes Request (Bundled)

POST /api/v1/solve/multiframes

Allows bundling of multiple multi-frame requests into one HTTP request. The HTTP request carries gateways and input objects where each input object denotes the message history for a device. The Geolocation Service returns a location estimate for each element of the input object (or null if no estimate could be computed for that particular device). The array of inputs can be from the same device that moved and stopped at different locations, or it can be from a number of static devices that have each made multiple transmissions without moving.

Request Headers

Request Body:

The request body contains an object with the following fields:

{
  "gateways": ARRAY,  // Required. Array of Gateway objects.
  "inputs":   [       // Required. Array of input objects (1<=n<=16).
    {
      "params":  OBJECT,  // Optional. Parameters object.
      "frames":  ARRAY    // Required. Array of Frame objects.
    }
  ]
}
  • gateways: Required. Array of v3Gateway objects. List of gateway decriptors.

  • inputs: Required. Array of input objects. At least one must be specified; a maximum of 16 elements can be included. Each object contains the following fields:

  • params: Optional. List of v3Parameters for the solver algorithm.

  • frames: Required. An array v3Frame instances.

Response:

Status Codes
Response Headers

Response JSON:

If the request executes successfully, the multiframes request responds with a result. The errors field denotes a non-empty array of error messages to be displayed if errors are encountered. If there are individual input entries that are insufficient or not valid, the warnings array will report those, if the array is not null.

{
   "result":   ARRAY,    // Optional. Array of entries with location solver results or null.
   "errors":   STRING[], // Optional. Array of error messages
   "warnings": STRING[]  // Optional. Array of warning messages, might be empty
}
  • result: Optional. If set, this is the v3LocationSolverResult, indicating the estimated location of the device. If null, no estimate could be computed

  • errors: Optional. If set, an array of error messages.

  • warnings: Optional. If set, an array of warning messages.

Example Request:

POST /api/v1/solve/multiframes HTTP/1.1
Host: mgs.loracloud.com
Accept: application/json
Content-Type: application/json
{
    "gateways": [
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-DF",
            "latitude": 47.012670,
            "longitude": 6.992070,
            "altitude": 446
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-C9",
            "latitude": 47.006389,
            "longitude": 6.966399,
            "altitude": 457
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-63",
            "latitude": 47.007700,
            "longitude": 6.960840,
            "altitude": 500
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-D5",
            "latitude": 46.998400,
            "longitude": 6.949220,
            "altitude": 500
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-0B",
            "latitude": 46.998490,
            "longitude": 6.941090,
            "altitude": 494
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-67",
            "latitude": 46.993333,
            "longitude": 6.930833,
            "altitude": 470
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-B3",
            "latitude": 47.000800,
            "longitude": 6.923770,
            "altitude": 603
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1A-5D",
            "latitude": 46.988860,
            "longitude": 6.912870,
            "altitude": 513
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-CF",
            "latitude": 46.980320,
            "longitude": 6.898680,
            "altitude": 455
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1B-E7",
            "latitude": 46.987990,
            "longitude": 6.893333,
            "altitude": 552
        },
        {
            "gatewayId": "00-00-E4-77-6B-00-1A-97",
            "latitude": 46.983753,
            "longitude": 6.906008,
            "altitude": 479
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-fe",
            "latitude": 47.006389,
            "longitude": 6.966399,
            "altitude": 457
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-7a",
            "latitude": 46.993333,
            "longitude": 6.930833,
            "altitude": 470
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-9a",
            "latitude": 47.000800,
            "longitude": 6.923770,
            "altitude": 603
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-cb",
            "latitude": 46.988860,
            "longitude": 6.912870,
            "altitude": 513
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-1e",
            "latitude": 46.980320,
            "longitude": 6.898680,
            "altitude": 455
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7f-d9",
            "latitude": 46.987990,
            "longitude": 6.893333,
            "altitude": 552
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-01-70",
            "latitude": 46.983753,
            "longitude": 6.906008,
            "altitude": 479
        },
        {
            "gatewayId": "E4-77-6B-FF-FF-00-1B-D1",
            "latitude": 45.24435,
            "longitude": 5.86380,
            "altitude": 100
        },
        {
            "gatewayId": "E4-77-6B-FF-FF-00-1B-EB",
            "latitude": 45.24672,
            "longitude": 5.86821,
            "altitude": 100
        },
        {
            "gatewayId": "E4-77-6B-FF-FF-00-1B-CD",
            "latitude": 45.24155,
            "longitude": 5.87360,
            "altitude": 100
        },
        {
            "gatewayId": "E4-77-6B-FF-FF-00-0F-2F",
            "latitude": 45.23920,
            "longitude": 5.86819,
            "altitude": 100
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-79-e8",
            "latitude": -4.067502,
            "longitude": 38.136771,
            "altitude": 1242
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7a-03",
            "latitude": -4.052783,
            "longitude": 38.106914,
            "altitude": 915
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-7a-6d",
            "latitude": -4.118728,
            "longitude": 38.169315,
            "altitude": 1114
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-79-e2",
            "latitude": -4.104836,
            "longitude": 38.078576,
            "altitude": 1358
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-79-e2",
            "latitude": -4.104836,
            "longitude": 38.078576,
            "altitude": 1358
        },
        {
            "gatewayId": "72-76-ff-ff-fe-01-79-e2",
            "latitude": -4.104836,
            "longitude": 38.078576,
            "altitude": 1358
        }
    ],
    "inputs": [
        {
            "frames": [
                [
                    ["00-00-E4-77-6B-00-1B-E7", 1, 158231921, -93.0, 15.0],
                    ["00-00-E4-77-6B-00-1B-E7", 0, 158231460, -98.0, 12.0],
                    ["00-00-E4-77-6B-00-1B-D5", 1, 158241881, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-D5", 0, 158241827, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-CF", 0, 158233064, -122.0, -7.0],
                    ["00-00-E4-77-6B-00-1B-67", 0, 0, -256.0, -6.0],
                    ["00-00-E4-77-6B-00-1A-97", 1, 158230926, -95.0, 3.0],
                    ["00-00-E4-77-6B-00-1A-97", 0, 158231135, -100.0, 12.0],
                    ["00-00-E4-77-6B-00-1A-5D", 1, 158231983, -97.0, 15.0],
                    ["00-00-E4-77-6B-00-1A-5D", 0, 158232113, -99.0, 15.0]
                ],
                [
                    ["00-00-E4-77-6B-00-1B-E7", 1, 159238843, -97.0, 11.0],
                    ["00-00-E4-77-6B-00-1B-E7", 0, 159238191, -106.0, 6.0],
                    ["00-00-E4-77-6B-00-1B-D5", 1, 159249033, -110.0, 4.0],
                    ["00-00-E4-77-6B-00-1B-D5", 0, 159248710, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-CF", 1, 159238286, -120.0, -6.0],
                    ["00-00-E4-77-6B-00-1B-CF", 0, 159239187, -117.0, -3.0],
                    ["00-00-E4-77-6B-00-1A-97", 1, 159238282, -98.0, -3.0],
                    ["00-00-E4-77-6B-00-1A-97", 0, 159238079, -107.0, -8.0],
                    ["00-00-E4-77-6B-00-1A-5D", 1, 159239130, -100.0, 10.0],
                    ["00-00-E4-77-6B-00-1A-5D", 0, 159238987, -94.0, 14.0]
                ]
            ],
            "params": {"locAlgType": "TDOA_ALG", "doRssiTdoaCombine": true}
        },
        {
            "frames": [
                [
                    ["00-00-E4-77-6B-00-1B-E7", 1, 158231921, -93.0, 15.0],
                    ["00-00-E4-77-6B-00-1B-E7", 0, 158231460, -98.0, 12.0],
                    ["00-00-E4-77-6B-00-1B-D5", 1, 158241881, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-D5", 0, 158241827, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-CF", 0, 158233064, -122.0, -7.0],
                    ["00-00-E4-77-6B-00-1B-67", 0, 0, -256.0, -6.0],
                    ["00-00-E4-77-6B-00-1A-97", 1, 158230926, -95.0, 3.0],
                    ["00-00-E4-77-6B-00-1A-97", 0, 158231135, -100.0, 12.0],
                    ["00-00-E4-77-6B-00-1A-5D", 1, 158231983, -97.0, 15.0],
                    ["00-00-E4-77-6B-00-1A-5D", 0, 158232113, -99.0, 15.0]
                ],
                [
                    ["00-00-E4-77-6B-00-1B-E7", 1, 159238843, -97.0, 11.0],
                    ["00-00-E4-77-6B-00-1B-E7", 0, 159238191, -106.0, 6.0],
                    ["00-00-E4-77-6B-00-1B-D5", 1, 159249033, -110.0, 4.0],
                    ["00-00-E4-77-6B-00-1B-D5", 0, 159248710, -113.0, 2.0],
                    ["00-00-E4-77-6B-00-1B-CF", 1, 159238286, -120.0, -6.0],
                    ["00-00-E4-77-6B-00-1B-CF", 0, 159239187, -117.0, -3.0],
                    ["00-00-E4-77-6B-00-1A-97", 1, 159238282, -98.0, -3.0],
                    ["00-00-E4-77-6B-00-1A-97", 0, 159238079, -107.0, -8.0],
                    ["00-00-E4-77-6B-00-1A-5D", 1, 159239130, -100.0, 10.0],
                    ["00-00-E4-77-6B-00-1A-5D", 0, 159238987, -94.0, 14.0]
                ]
            ],
            "params": {"locAlgType": "TDOA_ALG", "doRssiTdoaCombine": true}
        }
    ]
}

Example Response:

{
   "result":[
      {
         "numUsedGateways":5,
         "HDOP":1.0,
         "algorithmType": "RssiTdoaCombined",
         "locationEst":{
            "latitude":46.987555,
            "longitude":6.9027,
            "toleranceHoriz":75
         }
      },
      {
         "numUsedGateways":5,
         "HDOP":1.0,
         "algorithmType": "RssiTdoaCombined",
         "locationEst":{
            "latitude":46.987555,
            "longitude":6.9027,
            "toleranceHoriz":75
         }
      }
   ],
   "warnings":[]
}

Geolocation JSON Formats (single-/multi-frame)

Gateway

Gateway descriptions. Each gateway is specified by gatewayIdlatitudelongitude and altitude.

{
  "gatewayId":    STRING
  "latitude":     FLOAT
  "longitude":    FLOAT
  "altitude":     FLOAT
}
  • gatewayId: Required. String. An identifier for the gateway, e.g. MAC address or label. It must be unique within a query.

  • latitude: Required. Float. Latitude.

  • longitude: Required. Float. Longitude.

  • altitude: Required. Float. Altitude (in meters).

Example:

{
  "gatewayId":"CustomUniqueString",
  "latitude":51.50119,
  "longitude":-0.142003,
  "altitude":100
}

Frame

A frame stores the radio parameters captured by the reception of a LoRa® frame at the antenna of all the LoRa® gateways in an array of v3Uplink objects:

[
  UPLINK,  // Array of Uplink objects
  UPLINK,
   ...
]

Example:

[
 [ "0000123456789a00", 0, 256477, -100.0, 17.7 ],
 [ "0000123456789a00", 1, 256433, -105.0, 13.1 ],
 [ "0000123456789a01", 0, 258814, -116.0, 3.3 ],
 [ "0000123456789a01", 1, 259024, -118.0, -2.7 ],
 [ "0000123456789a02", 0, 259940, -116.0, 3.5 ],
 [ "0000123456789a02", 1, 261383, -113.0, 0.7 ]
]

Details the radio parameters captured by the reception of a LoRa® frame at the antenna of the LoRa® gateway’s antenna in a tuple with 5 elements:

[ GATEWAY,  // STRING, Gateway reference
  ANTENNA,  // UINT or null, Antenna Id (0 or 1)
  TDOA,     // UINT32 or null, Timestamp
  RSSI,     // FLOAT, RSSI
  SNR       // FLOAT, Snr
]
  • GATEWAY: An identifier for the gateway, i.e. gatewayId, as listed in the gateways parameter in the request.

  • ANTENNA An identifier for the antenna, in the form of an integer: 0 or 1. Can be set to null if unknown.

  • TDOA: TDOA timestamp. (uint32). If no TDOA timestamp is available from the gateway, set to null.

  • RSSI: Received Signal Strength Indicator value in dBm. Float.

  • SNR: Signal-to-Noise ratio value. Float.

Example:

[ "00-00-E4-77-6B-00-1A-5D", 0, 611795075, -86.0, 15.0 ]

Parameters

Requests for the estimation of locations can carry an optional set of parameters for the location solver. The locAlgType is used to select the location estimate based on the RSSI/SNR or TOA. The TOA solver can be further configured with doRssiTdoaCombine. If doRssiTdoaCombine is set to ‘true’, the solver combines the TOA and RSSI analysis.

{
  "locAlgType":        STRING,  // "TDOA_ALG" or "RSSI_ALG"
  "doRssiTdoaCombine": BOOLEAN
}

Parameter

doRssiTdoaCombine

True

False

locAlgType

RSSI_ALG

RSSI loc.

RSSI loc.

TDOA_ALG

TDOA loc, fallback on RSSI if needed

TDOA only loc.

By default, when no Parameter object is provided when invoking this API, the locAlgType is set to TDOA_ALG and doRssiTdoaCombine is set to to ‘true’.

Location Solver Result

Stores a computed position and statistics.

{
  "numUsedGateways":  UINT2,
  "HDOP":             FLOAT_OR_NULL,  // null if not applicable
  "algorithmType":    STRING,         // "Tdoa", "Rssi" or "RssiTdoaCombined"
  "locationEst": {
    "latitude":       FLOAT,
    "longitude":      FLOAT,
    "toleranceHoriz": INT
}
  • numUsedGateways: Required. uint8. Number of contributing gateways.

  • HDOP: Required, valid float or null. Horizontal dilution of precision. This value gives a measure of how well the number and relative positions of the gateways contribute to an accurate location estimate. The expected values range from 0.5 to 35. Smaller HDOP values typically suggest better location estimates. If HDOP is not available, this field is set to null.

  • algorithmType: Required. String. Only to be evaluated by clients if the value is one of the following:

    • Tdoa: Estimation based on TOA analysis

    • Rssi: Estimation based on RSSI/SNR analysis

    • RssiTdoaCombined: Estimation based on TOA and RSSI/SNR analysis

  • locationEst: Required. Object. Stores the estimated location and estimated inaccuracy in an object with the following fields:

    • longitude: Required. Float. Longitude.

    • latitude: Required. Float. Latitude.

    • toleranceHoriz: Required. INT. Error estimate for latitude and longitude (in meters).

Did this article help you?

Stay updated with the latest developments. Learn how to build location-aware applications.