Streaming Interface

Target Audience

This guide is intended for developers who would like to use Otonomo's vehicle data streaming capability.

Streaming Functionality Overview

Otonomo REST APIs support serving vehicle data by having data consumers 'pull' data using HTTP GET requests that are initiated by the data consumer side.
However, real-time vehicle data is often better served through a push mechanism, which ensures minimal delay and packet loss.
Otonomo provides a streaming mechanism that uses HTTP POST requests for pushing data to the data consumer.
Currently, the streaming mechanism works with aggregate data, while personal data is under beta.
Streaming lets data consumers define filters, such as attribute list, geo-fencing, and maximum latency, so they get only their desired data.

Subscribing to a New Stream

To subscribe to a new stream, an e-mail should be sent to Otonomo support inbox - [email protected]
The email needs to include the following details:

  • Norm Attributes - A list of attributes. The stream will issue data points that include these listed attributes.
  • Locations (Mandatory) - A list of countries / states / cities. The stream will send data on any point that originated in those locations.
  • Polygon (Optional) - A list of polygons. If a polygon is provided, the stream will include points that are within the polygon and the listed locations.
  • Latency (Optional) - Time unit in seconds. The stream will only send data points whose 'age' is below the latency threshold. The referenced time is the time the point was generated in the vehicle.
  • Hosting_server (Mandatory) - A URL / Hostname of your hosting server that will receive the POST request from Otonomo.
  • Authorization method - An authorization method for Otonomo POST requests. By default, we use an Authorization header with a Secret.

Once the e-mail is received, we will process your request within two business days.

The Vehicle Data Stream

Once the stream was created, Otonomo will start sending HTTP POST messages, containing vehicle data, to the call-back URL provided on the stream subscription API.
Every one second a new HTTP POST request is executed with all the accumulated vehicle data points from the previous POST request.
Each request can contain up to 1,000 vehicle data points. If no new points have arrived since last request, new request will not be issued.
In case Otonomo fails to push the data several times, there is no retroactive pushing of the data while the feed was down.

curl -X POST \
   https://{hosting-server URL} \
   -H 'Content-Type: application/json' \
   -H 'Authorization: {secret}'
   -d '{Body - see below}'

The request payload is a standard JSON message with three keys:
"subscription_id", "num_of_records", and 'data' key:

  • subscription_id: the stream ID.
  • data: a list of vehicle messages grouped into data points.
  • num_of_records: represents the number of records in the current response

Here is an example body of a request:

{
  "data": [
    {
      "metadata__time__epoch": 1557060437000,
      "vehicle__identification__otonomo_id": "33f0da57aa025edca68bf29d51278e87",
      "location__latitude__value": 7,
      "location__longitude__value": -162,
      "mobility__heading__angle": 182,
      "mobility__speed__value": 124
    },
    {
      "metadata__time__epoch": 1557060440000,
      "vehicle__identification__otonomo_id": "33f0da57aa025edca68bf29d51278e87",
      "location__latitude__value": -49,
      "location__longitude__value": 16,
      "mobility__heading__angle": 60,
      "mobility__speed__value": 181
    }
  ],
  "num_of_records": 2,
  "subscription_id": "01fba5398b7d4055a12fe6a7a6cd79c4"
}

If you have any questions, feel free to contact us at [email protected]