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

[{"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