ETA Push

Introduction

Simacan's Control Tower can push its known estimated arrival times (ETAs) for all active trips and stops and all ETA updates via HTTP POST method to your platform's HTTPS endpoint. We call this the ETA push service. Using this service you can process our data into your own, or partner platform. Updates are real-time. Any GPS location update on a trip triggers a recalculation of the trip-routes and, as a result, updated ETAs for all next stops. Once you've set up this push service, no further manual action required.

The goal of this page is to explain the structure of the OTM5 messages that are shared using the eta-push. For further information on how to initiate a connection see the overview page.

Note that this pages replaces the outdated, but still supported older ETA push.

Message Structure

The messages in the planning push follow the OTM5 Trip Profile.

General structure

Copy

Copied

trip
  name
  externalAttributes
  contextEvents
    locationUpdate (of the last known position of the vehicle.)
  actors (shipper, carrier)
  actions
    stop
      location
      lifecycle = planned
      start and end times
    stop
      location
      lifecycle = projected
      start and end times

Full Message Example

Here is an example of an ETA message. It is similar to the planned and realized trips, however it contains less details since those are not relevant for timeliness.

Note that every stop except for the first will appear twice in the message. Once in the planned lifecycle, and once in the projected lifecycle. The planned lifecycle contains the times as originally planned by the planning system. However, due to traffic jams, road closures, occupied dock, or other situations the expected time of arrival might be different. The projected lifecycle contains the times of the stop based on our calculations based on historical and actual traffic data, combined with the current position of the vehicle.

We cannot give a projected start and end time of the first stop since the vehicle has not started yet, therefore only stops after the first will have ETAs.

Copy

Copied

{
  "id": "9bb6c768-7567-5e05-ae6a-7fd4baf6f83f",
  "name": "Trip 12345",
  "externalAttributes": {
    "tripId": "12345"
  },
  "context": [
    {
      "entity": {
        "id": "b0517f03-c9b2-315c-8259-590007596f82",
        "creationDate": "2022-10-27T08:29:03Z",
        "lifecycle": "realized",
        "geoReference": {
          "lat": 52.060829,
          "lon": 5.111589,
          "heading": {
            "value": 213,
            "unit": "°"
          },
          "type": "latLonPointGeoReference"
        },
        "eventType": "locationUpdateEvent"
      },
      "associationType": "inline"
    }
  ],
  "actors": [
    {
      "entity": {
        "id": "8a18ee3a-12bd-3667-9830-1ef75a512436"
      },
      "roles": [ "carrier" ],
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "7be69d45-4f4c-3876-81e1-44f9060ed278"
      },
      "roles": [ "shipper" ],
      "associationType": "inline"
    }
  ],
  "actions": [
    {
      "entity": {
        "id": "0cfa0e7e-fa2a-3845-ba57-8146106803e0",
        "externalAttributes": {
          "stopId": "s1"
        },
        "lifecycle": "planned",
        "sequenceNr": 0,
        "location": {
          "entity": {
            "id": "a07eea71-615f-49c2-917f-288f7135f8e3",
            "name": "Start location",
            "externalAttributes": {
              "locationId": "1384"
            },
            "geoReference": {
              "lat": 52.07872058,
              "lon": 5.05797124,
              "type": "latLonPointGeoReference"
            },
            "administrativeReference": {
              "name": "display name of the location",
              "street": "street",
              "houseNumber": "1",
              "postalCode": "ABCD00",
              "city": "Amsterdam",
              "country": "NL"
            }
          },
          "associationType": "inline"
        },
        "startTime": "2022-10-27T06:12:00Z",
        "endTime": "2022-10-27T06:27:00Z",
        "actionType": "stop"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "5c7f50e0-6e20-3259-bd80-bb59cea5f913",
        "externalAttributes": {
          "stopId": "s2"
        },
        "lifecycle": "planned",
        "sequenceNr": 1,
        "location": {
          "entity": {
            "id": "897be952-ad77-476e-8587-acdf2e2c6c28",
            "name": "Klant 1",
            "externalAttributes": {
              "groupingAddressId": "1384",
              "locationId": "9017710799"
            },
            "geoReference": {
              "lat": 52.082474,
              "lon": 5.091418,
              "type": "latLonPointGeoReference"
            },
            "administrativeReference": {
              "name": "Klant 1",
              "street": "Rachmaninoffplantsoen",
              "houseNumber": "227",
              "postalCode": "3533JZ",
              "city": "UTRECHT",
              "country": "NL"
            }
          },
          "associationType": "inline"
        },
        "startTime": "2022-10-27T06:37:00Z",
        "endTime": "2022-10-27T06:46:00Z",
        "actionType": "stop"
      },
      "associationType": "inline"
    },
    {
      "entity": {
        "id": "5c7f50e0-6e20-3259-bd80-bb59cea5f913",
        "externalAttributes": {
          "stopId": "s2"
        },
        "lifecycle": "projected",
        "sequenceNr": 1,
        "location": {
          "uuid": "897be952-ad77-476e-8587-acdf2e2c6c28",
          "entityType": "location",
          "associationType": "reference"
        },
        "startTime": "2022-10-27T06:23:45.241Z",
        "endTime": "2022-10-27T06:32:45.241Z",
        "actionType": "stop"
      },
      "associationType": "inline"
    }
  ]
}