Data Push

Introduction

After the Simacan platform receives planning data and real-time GPS updates come in, data is enriched and combined within the Simacan platform. These enrichments and updates can be shared using one or multiple data push connections. There are three types of data push connections possible:

  • Planning Push : get planning data at the moment it comes in or changes. This includes enrichments such as vehicle couple information, or other carrier planning data.
  • ETA Push : based on the trip planning, incoming GPS updates of the vehicle, and actual traffic information Simacan calculates estimated arrival times. These calculations can be shared using the ETA Push.
  • Realized Trip Push : once trips complete both the original planned and realized data is available. This data can then be analyzed to ensure more accurate planned trips in the future.

The nature for each of these services is different. Realized trips are only shared once, since they are only completed once and do not change anymore. Planned trips can change quite frequently, depending on the planning system. ETAs are calculated for every trip for every GPS updates that comes in, so be aware of a high load.

You can choose to connect to one or multiple of the data push services. Each connection can be configured separately, so it is possible to use different URLs for the different use cases.

What we need from you

First you need to set up an endpoint where we can POST or PUT our data to. To be safe, please secure your endpoint with Basic access authentication or OAuth2. Next deliver us, the following details:

For Basic Access Authentication

  • HTTPS URL of your endpoint.
    • We only support TLS 1.2 for now.
    • We accept self-signed server certificates as well as client certificates.
  • HTTP Method (PUT or POST).
  • Username & password for your endpoint.
    • Any form of two HTTP headers, like Basic Auth.
    • Any other form of authorization that can be configured using a custom header.
    • At least we expect a 200 response.

For OAuth2

  • URL for your OAuth2 Authorization url.
    • We support password grant or client credentials grant.
    • We support public and confidential clients.
    • For confidential clients, client credentials can be sent using a (Basic) authorization header or as part of the request body using the "client_secret" field.
  • HTTPS URL of your endpoint.
    • We only support TLS 1.2 for now.
    • We accept self-signed server certificates as well as client certificates.
  • HTTP Method (PUT or POST).

What we will deliver to you

Once we have the correct details of your endpoint, we can start sending you data. Our data will be in JSON hierarchical structure based on the OTM5 trip profile.

All updates are sequential, they will always been sent to you in the order of which updates were made. Even if the connection was lost for whatever reason, we will still send you all updates, so that you get a complete picture of the changes and how they were made (within a time frame of less than 96 hours).

Technical notes

  • We will use the OTM5 standard, based on the trip profile .
  • An individual message will always contain a single trip.
  • Be ready for peak consumption, whehter you get planning updates or ETAs, or even realized trips. They often happen in bulk, resulting in many updates at the same time.