Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Northbound API Reference


(warning)

Warning

Programmable Asset Tracker Private Beta

The Twilio Programmable Asset Tracker is in a pre-release phase and the information contained in this document is subject to change. Some features referenced below may not be fully available until the Programmable Asset Tracker reaches General Availability (GA) release.

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.

(information)

Info

What follows covers the 'standard' Northbound API — the API defined by the open source Asset Tracker application Twilio provides. However, because the API is defined by the application, and the application is completely customizable by you, you can if you wish adjust, extend, and even replace the Northbound API if you wish. The standard API gets you started, but it may be just the first step on your Asset Tracker development journey.


How to implement the Northbound API

how-to-implement-the-northbound-api page anchor

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

api-requirements page anchor
  • 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.

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.

Key NameValueNotes
trackerIdStringThe Asset Tracker's unique hardware ID
timestampNumberA Unix epoch timestamp in seconds indicating when the request was sent by the Asset Tracker's agent
statusObjectA status readout — see below for details
locationObjectThe Asset Tracker's last known location — see below for details
sensorsObjectThe latest on-board sensor readings.The value of the key temperature is the temperature in Celsius.The value of the key batteryLevel is the battery charge as a percentage
alertsArray of StringsWhich alerts have been posted. The array will be empty if no alerts have been triggered, otherwise it may contain any of the following strings: temperatureHigh,temperatureLow,shockDetected,batteryLow,motionStarted,motionStopped,geofenceEntered,geofenceExited,repossessionActivated,tamperingDetected
cellInfoObjectCellular information. Optional. Can be missed or empty if no new information available — see below for details
gnssInfoObjectGNSS information. Optional. Can be missed or empty if no new information available — see below for details
Key NameValueNotes
inMotionBooleanIndicates whether the Asset Tracker if currently moving (true) or static (false). The key will be absent if motion tracking is not enabled
inGeofenceBooleanIndicates whether the Asset Tracker is inside an active geofence (true) or outside it (false). The key will be absent if a geofence is not enabled
repossessionBooleanIndicates whether the Asset Tracker is in repossession mode (true) or not (false). The key will be absent if repossession mode is not enabled
Key NameValueNotes
timestampNumberA Unix epoch timestamp in seconds indicating when the location data was collected
typeStringIndicates how the location was determined. It will be one of the following strings: ble, gnss, wifi+cell, wifi or cell
accuracyNumberThe location accuracy in meters
latNumberThe Asset Tracker's latitude coordinate
lonNumberThe Asset Tracker's longitude coordinate
Key NameValueNotes
timestampNumberA Unix epoch timestamp in seconds indicating when this information was obtained
modeStringThe cellular service mode: "NOSERVICE", "GSM", "eMTC" or "NBIoT"
mccStringThe visited network's three-character Mobile Country Code
mncStringThe visited network's three-character Mobile Network Code
signalStrengthNumberThe cellular modem's measured RSSI
Key NameValueNotes
timestampNumberA Unix epoch timestamp in seconds indicating when this information was obtained
satellitesUsedNumberIndicates how the location was determined. It will be one of the following strings: ble, gnss, wifi+cell, wifi or cell

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.


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


How the Asset Tracker uses the API

how-the-asset-tracker-uses-the-api page anchor

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.

Rate this page: