Menu

Expand
Rate this page:

Northbound API Reference

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.

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

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.

To learn how to set environment variables in impCentral, the Electric Imp online IDE and device management console, please see the Electric Imp Dev Center.

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.

Key Name Value Notes
trackerId String The Asset Tracker’s unique hardware ID
timestamp Number A Unix epoch timestamp in seconds indicating when the request was sent by the Asset Tracker’s agent
status Object A status readout — see below for details
location Object The Asset Tracker’s last known location — see below for details
sensors Object The 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
alerts Array of Strings Which 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
cellInfo Object Cellular information. Optional. Can be missed or empty if no new information available — see below for details
gnssInfo Object GNSS information. Optional. Can be missed or empty if no new information available — see below for details

status

Key Name Value Notes
inMotion Boolean Indicates whether the Asset Tracker if currently moving (true) or static (false). The key will be absent if motion tracking is not enabled
inGeofence Boolean Indicates 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
repossession Boolean Indicates whether the Asset Tracker is in repossession mode (true) or not (false). The key will be absent if repossession mode is not enabled

location

Key Name Value Notes
timestamp Number A Unix epoch timestamp in seconds indicating when the location data was collected
type String Indicates how the location was determined. It will be one of the following strings: ble, gnss, wifi+cell, wifi or cell
accuracy Number The location accuracy in meters
lat Number The Asset Tracker’s latitude coordinate
lon Number The Asset Tracker’s longitude coordinate

cellInfo

Key Name Value Notes
timestamp Number A Unix epoch timestamp in seconds indicating when this information was obtained
mode String The cellular service mode: "NOSERVICE", "GSM", "eMTC" or "NBIoT"
mcc String The visited network’s three-character Mobile Country Code
mnc String The visited network’s three-character Mobile Network Code
signalStrength Number The cellular modem’s measured RSSI

gnssInfo

Key Name Value Notes
timestamp Number A Unix epoch timestamp in seconds indicating when this information was obtained
satellitesUsed Number Indicates how the location was determined. It will be one of the following strings: ble, gnss, wifi+cell, wifi or cell

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.
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif