REST API Documentation
Changes from v1.0
- Version 1.1 of the API adds the possibility to request all devices.
- Device information contains the direct status of trap_1 and trap_2: Either true for triggered or false for not triggered.
General
traplinked offers a read-only and rate limited REST API for developers to fetch information in JSON format.
Basic user flow
If a user wants to connect a traplinked device with third party software an API token is needed. With this token it's possible to request the data for all devices attached to the customer account.
To request data for specific devices a device serial number is needed. The device serial number can be found in the web app or on the device itself. Additionally the web app will create a QR code which encodes the serial number.
Additionally to fetching data of devices it's possible to fetch information for all devices of a location excluding devices from sub-locations. To achieve this the location path must be provided in the request instead of a device serial number. A QR code containing the location path will be shown in the web app.
API tokens
Access to the API is restricted using an API token. The token can be managed by an admin user in the settings of the web app.
Authentication
The API uses tokens to authenticate requests. All requests must be authenticated. Authentication is performed via Bearer Authentication.
Authentication: Bearer <token>
Requests
All requests must be made over HTTPS. Data can be fetched using GET requests. The base URL is
https://api.traplinked.com/api/v1.1/
To fetch devices data the path 'devices' is needed.
https://api.traplinked.com/api/v1.1/devices
To always use the latest version of a major release the following URL can be used:
https://api.traplinked.com/api/v1/
Parameters
Requests take either no parameter, a list of devices or a location path as parameter. If both parameters are sent only the list of devices will be used.
| Name | Description | Example |
|---|---|---|
| ids | A comma separated list of devices serial numbers. | 1A11BC,DEF222 |
| location_path | An URL encoded path to a location. The path starts with a '//'. Locations and sub locations are separated by a '//'. | %2F%2Fmy%2F%2Fpath |
Responses
Responses are sent in JSON format. The response is an array of devices. Only mandatory fields are returned for every request. Optional fields are only sent if they're available.
| Name | Type | Optional | Description |
|---|---|---|---|
| name | String | Mandatory | Name of the device. Can be changed by the user. Default name is the serial number. |
| serial_number | String | Mandatory | Serial number of the device. Example: 1A11BC |
| type | Integer | Mandatory | The device type. See device type section for further details. |
| status | Integer | Mandatory | The status of the device. See device status section for further details. |
| battery_status | Decimal | Mandatory | Battery status of the device. A value between 0.0 and 1.0. |
| description | String | Optional | Device description. Can be changed by the user. |
| last_heartbeat | Datetime | Optional | Last time the device connected to the server in UTC. Example: 2020-01-01T12:00:00 |
| latitude | Decimal | Optional | Latitude of the device. |
| longitude | Decimal | Optional | Longitude of the device. |
| transfer_mode | Integer | Mandatory | Connection type. See transfer mode section for further details. |
| location | Location data | Optional | Location data. See location data section for further details. |
| trap_1 | Bool | Optional | Status of trap_1: "true" for triggered, "false" for not triggered |
| trap_2 | Bool | Optional | Status of trap_2: "true" for triggered, "false" for not triggered |
Device type
| Type | Description |
|---|---|
| 0 | JERRY |
Device status
| Status | Description |
|---|---|
| 0 | Device is inactive. |
| 1 | Device is active. |
| 2 | Heartbeat failed. |
| 3 | Device has triggered. |
| 4 | Battery is low. |
| 5 | Location mode is active. |
| 6 | Unstable Wi-Fi connection. |
Transfer mode
| Mode | Description |
|---|---|
| 0 | Wi-Fi |
| 1 | LoRa |
Location data
If the device is not assigned to a location, this field is missing. If devices for a location path are requested location data is omitted.
| Name | Type | Optional | Description |
|---|---|---|---|
| name | String | Mandatory | The name of the location. |
| address | String | Optional | The address of the location. |
Errors
Errors are signaled through HTTP status codes.
| Code | Description |
|---|---|
| 200 | Successful request |
| 400 | Bad request |
| 401 | Unauthorized |
| 429 | Too many requests |
| 500 | Internal server error |
Examples
Getting all device data
Request
curl "https://api.traplinked.com/api/v1.1/devices" -H "Accept: application/json" -H "Authorization: Bearer MyToken"
Response
{
"devices": [
{
"type": 0,
"name": "My JERRY Device",
"serial_number": "1A11BC",
"description": "Description",
"status": 3,
"battery_status:": 1,
"last_heartbeat": "2020-01-01T12:00:00",
"latitude": 49.455556,
"longitude": 11.078611,
"transfer_mode": 0,
"location": {
"name": "Device location",
"address": "My Address"
}
}
]
}
Getting device data
Request
curl "https://api.traplinked.com/api/v1.1/devices?ids=1A11BC" -H "Accept: application/json" -H "Authorization: Bearer MyToken"
Response
{
"devices": [
{
"type": 0,
"name": "My JERRY Device",
"serial_number": "1A11BC",
"description": "Description",
"status": 3,
"battery_status:": 1,
"last_heartbeat": "2020-01-01T12:00:00",
"latitude": 49.455556,
"longitude": 11.078611,
"transfer_mode": 0,
"location": {
"name": "Device location",
"address": "My Address"
}
}
]
}
Getting location data
Request
curl "https://api.traplinked.com/api/v1.1/devices?location_path=%2F%2FMyLocation" -H "Accept: application/json" -H "Authorization: Bearer MyToken"
Response
{
"devices": [
{
"type": 0,
"name": "My JERRY Device",
"serial_number": "1A11BC",
"description": "Description",
"status": 3,
"battery_status:": 1,
"last_heartbeat": "2020-01-01T12:00:00",
"latitude": 49.455556,
"longitude": 11.078611,
"transfer_mode": 0
}
]
}
Testing
To test the API connection you can use the following data:
| Description | Value |
|---|---|
| API URL | https://api.traplinked.com/api/v1.1 |
| API token | abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012 |
| Device serial numbers | TESTDEVICE1, TESTDEVICE2, TESTDEVICE3 |
| Location path | //MyLocation |
Examples
curl "https://api.traplinked.com/api/v1.1/devices" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
curl "https://api.traplinked.com/api/v1.1/devices?location_path=%2F%2FMyLocation" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
curl "https://api.traplinked.com/api/v1.1/devices?ids=TESTDEVICE1,TESTDEVICE2" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Questions?
If you have questions regarding our API, please contact us at: api@traplinked.com