Tracking Device API
Context
The Tracking Device API is a unified interface to post or request information about tracking devices. Usually a tracking device is a vehicle, which needs to be registered to our platform before you can feed GPS data to other endpoints. A tracking device can be used to track a truck, but can be a trailer or any other moving object. For this guide we only track GPS data, but a device could be able to track other data as well, like heading, temperature, engine running or doors open/closed.
Example
Register (or update) a tracking device
As mentioned before, we are first going to register a tracking device on the Simacan Platform. We can do this by sending a small payload to the baseURI in either a PUT or POST request method.
A small word of caution: if your `externalDeviceId` is already known on our platform, we will update its record.
Payload
Below is an example payload you could send:
{
"externalDeviceId": "1234",
"externalSystemId": "fms-janszoon_transport",
"active": true,
"carrierCode": "",
"customerDeviceId": "",
"licensePlate": "AB-12-CD",
"driverName": "Harry de Vries"
}
In this example the externalDeviceId
indicates the unique Id as used on your own platform; active can be set to
true or false to indicate if the device is in use. And carrierCode
is the unique identifier for your carrier account,
which you should obtain from Simacan.
Send it
The next example will only work, if you obtained a bearer token from our Auth API. Include this in the header. Here we post to the staging URL
curl -d "{
\"externalDeviceId\": \"1234\",
\"externalSystemId\": \"fms-janszoon_transport\",
\"active\": true,
\"carrierCode\": \"\",
\"customerDeviceId\": \"\",
\"licensePlate\": \"AB-12-CD\",
\"driverName\": \"Harry de Vries\" }"
-H "Content-Type: application/json"
-H "Authorization: Bearer eyXXX"
-X POST -i https://tracking-device-api-stg.services.simacan.com/api/public/v2/
Now let’s check if we successfully registered our first device
Response
If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this
successful operation
Response Schema: application/json
deviceUUID | string This is the Simacan generated universally unique identifier |
externalSystemId | string Identifier for the source system we use to uniquely recognize the shipper/carrier |
externalDeviceId | string The identifier you use to recognize the device/vehicle in your source system |
customerDeviceId | string |
active | boolean Indicates whether the current tracking device is active or not |
relation | string |
carrierCode | string This code is used by the Simacan Control Tower to match a Tracking Device with a carrier |
creationDate | string Timestamp when record was created |
lastUpdatedDate | string Timestamp when record was updated |
licensePlate | string License Plate linked with the current tracking device |
driverName | string Driver name linked with the current tracking device |
attributes | object Any freeform additional attributes |
[- {
- "deviceUUID": "b9ed42ff-3ffb-4418-9498-5eb0ba308899",
- "externalSystemId": "fms-janszoon_transport",
- "externalDeviceId": "1234",
- "customerDeviceId": "string",
- "active": "true",
- "relation": "janszoon_transport",
- "carrierCode": "string",
- "creationDate": "2020-06-07T09:17:43Z",
- "lastUpdatedDate": "string",
- "licensePlate": "AB-12-CD",
- "driverName": "string",
- "attributes": {
- "carBrand": "Mercedes"
}
}
]
Great! You’ve just successfully registered your first device on our platform.
API Marketplace
For a more detailed reference in the Tracking Device API, visit our API Marketplace