OTM5 Realisation Data

Context

Once a trip is in progress, we process the GPS updates as realisation points. The most recent information from your “tracking device”, should be delivered to our platform often for more accurate trip monitoring. Simacan provides an API for sending these realisation points using the OTM5 format.

Schema & examples

OTM5 realisation data comes in three shapes:

  1. By sending the coordinates along with the trip ID the update belongs to.
  2. By sending the coordinates along with the license plate of the vehicle the update belongs to. If the vehicle is not yet known it will be created on demand.
  3. By sending the coordinates along with the device ID of the vehicle the update belongs to. If the vehicle is not yet known it will be created on demand.

An example of the first looks like this:

Copy
Copied
{
    "eventType": "locationUpdateEvent",
    "creationDate": "2021-10-27T09:00:31Z",
    "externalAttributes": {
      "tripId": "my-trip-id",
    },
    "lifecycle": "actual",
    "actors": [{
        "entity": { "name": "some-shipper" },
        "roles": ["shipper"],
        "associationType": "inline"
      },
      {
         "entity": { "name": "some-carrier" },
         "roles": ["carrier"],
         "associationType": "inline"
      }
   ],
   "geoReference": {
        "lat": 52,
        "lon": 7,
        "type": "latLonPointGeoReference"
    }
}

An example of the second looks like this:

Copy
Copied
{
    "eventType": "locationUpdateEvent",
    "creationDate": "2021-10-27T09:00:31Z",
    "lifecycle": "actual",
    "actors": [{
        "entity": { "name": "some-shipper" },
        "roles": ["shipper"],
        "associationType": "inline"
      },
      {
         "entity": { "name": "some-carrier" },
         "roles": ["carrier"],
         "associationType": "inline"
      }
   ],
    "vehicle": {
        "entity": {
            "vehicleType": "Truck",
            "licensePlate": "AA-BB-CC"
        },
        "associationType": "inline"
    },
    "geoReference": {
        "lat": 52,
        "lon": 7,
        "speed": {
            "value": 0,
            "unit": "km/h"
        },
        "heading": {
            "value": 0,
            "unit": "degrees"
        },
        "type": "latLonPointGeoReference"
    }
}

An example of the third looks like this:

Copy
Copied
{   
    "eventType": "locationUpdateEvent",
    "creationDate": "2021-10-27T09:00:31Z",
    "lifecycle": "actual",
    "vehicle": {
        "entity": {
            "externalAttributes": {
                "vehicleId": "some-device-id"
            }
        },
        "associationType": "inline"
    },
    "actors": [{
            "entity": { "name": "some-shipper"},
            "roles": ["shipper"],
            "associationType": "inline"
        },
        {
            "entity": { "name": "some-carrier"},
            "roles": ["carrier"],
            "associationType": "inline"
        }
    ],
    "geoReference": {
        "lat": 52,
        "lon": 7,
        "speed": {
            "value": 0,
            "unit": "km/h"
        },
        "heading": {
            "value": 0,
            "unit": "degrees"
        }
    }
}

As can be seen from both versions there are a few mandatory parts:

  • Each message needs to be of the type locationUpdateEvent . Any other OTM5 event types will be rejected with a validation error.
  • Each message needs to have actors, we require both the carrier and shipper information.
  • Each message needs a couple id . As mentioned above, this can either be the trip ID in the external attributes or the vehicle. If both are provided the trip ID will be used and the vehicle will be ignored.
  • Each message with only license plate or vehicle ID, requires a call to the couple API to assign the vehicle to a trip.
  • Each message needs coordinates. The speed and heading can be optionally provided in both cases.
  • Each message expects the lifecycle actual and the creation date of the update.

Send it

This example only works, if you obtained a bearer token from our Auth API. Include this in the header. Here we post to the production URL

Copy
Copied
curl -X PUT \
  https://otm5-realisation-receiver.services.simacan.com/api/v5/events \
  -H "Authorization: Bearer eyXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "locationUpdateEvent",
    "creationDate": "2021-10-27T09:00:31Z",
    "externalAttributes": {
      "tripId": "my-trip-id"
    },
    "lifecycle": "actual",
    "actors": [{
        "entity": { "name": "some-shipper" },
        "roles": ["shipper"],
        "associationType": "inline"
      },
      {
         "entity": { "name": "some-carrier" },
         "roles": ["carrier"],
         "associationType": "inline"
      }
   ],
   "geoReference": {
        "lat": 52,
        "lon": 7,
        "type": "latLonPointGeoReference"
    }
}'

Response

If you receive an HTTP status code 200 OK, you have confirmed you are sending data correctly. You can start sending all your updates to our platform.

Great! You are totally set to send tracking data updates for specified tracking devices