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.
- The URL and path preceding the endpoint is set using the impCentral environment variable
- Accept the message body in JSON format.
- The message will use the
content-type: application/json
header.
- The message will use the
- 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 POST
s 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.
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.