Last updated 3 months ago

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
Array ()
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

Content type
application/json
[
  • {
    }
]

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