Northbound API Reference

The Programmable Asset Tracker operates in conjunction with two REST APIs. One, the “Southbound API”, is hosted by the Asset Tracker’s in-cloud companion app and is used to read and update the device’s configuration remotely. The other, the “Northbound API” specifies the API that the Asset Tracker expects to communicate with when it contacts a remote server to provide status data.

This guide focuses solely on the Northbound API.

How to implement the Northbound API

To allow a Asset Tracker to transfer data to your cloud, you need to implement an endpoint that meets the criteria listed below and is able to extract the information you need from the JSON payload described shortly. You can use whatever language or tools you prefer to program your server.

API requirements

• Accept POST requests to the endpoint /data.
  • The URL and path preceding the endpoint is set using the impCentral environment variable CLOUD_REST_API_URL. This will be compiled in when you build and deploy a new version of the Asset Tracker application. The Asset Tracker adds /data to the end of this URL.
• Accept the message body in JSON format.
  • The message will use the content-type: application/json header.
• Support Basic authentication.
• Return the HTTP response code 200 when the message is received or accepted. Any other value will be interpreted by the Asset Tracker application as an error.

API data format

The message data will be sent to the endpoint you implement. It will arrive as JSON with the following key-value pairs. All keys will be included unless specified otherwise.

status

location

cellInfo

gnssInfo

Example

This is a sample data payload that an Asset Tracker might POST to your Northbound API implementation. You can use this a API test data.

{
  "trackerId": "c0010c2a69f088a4",
  "timestamp": 1617900077,
  "status": {
    "inMotion": true,
    "repossession": false
  },
  "location": {
    "timestamp": 1617900070,
    "type": "gnss",
    "accuracy": 3,
    "lng": 30.571465,
    "lat": 59.749069
  },
  "sensors": {
    "batteryLevel": 100,
    "temperature": 42.191177
  },
  "alerts": [
    "temperatureHigh",
    "shockDetected"
  ],
  "cellInfo": {
    "timestamp": 1617900010,
    "mode": "eMTC",
    "mcc": "244",
    "mnc": "05",
    "signalStrength": -41
  },
  "gnssInfo": {
    "timestamp": 1617900070,
    "satellitesUsed": 5
  }
}

How the Asset Tracker uses the API

The Asset Tracker will make periodic status POSTs to the API provided it has been given the target URL and the credentials it needs to access that URL.

These values are entered as impCentral environment variables, which are compiled into the application when it is built and deployed. The environment variables you need to set are listed below. No default value is provided, and you should consider them mandatory:

• CLOUD_REST_API_URL The target URL excluding the endpoint, /data.
• CLOUD_REST_API_USERNAME The target server username.
• CLOUD_REST_API_PASSWORD The target server password.