otonomo-docs

Test Drive Vehicle Data from Otonomo

Our connected car data is now accessible for developers

Aggregated Data Demo Service

Otonomo's aggregated data demo Service enables consumers to experiment with
aggregated and raw vehicle data.

Overview
Accessing Aggregated Historical Data
Step 1: Obtain a General Access Token
Step 2: Request Predefined Historical Data
Step 3: Check the Status
Step 4: Download

Overview

The demo service is created automatically after the user has completed the signup process.

What's included in the demo service?

The demo service provides simulated vehicle data. The collected data is from January 14th, 2019 at 12:00am to January 20th, 2019 at 11:59pm and the vehicles are located in the UK.

There are 38 data attributes that are accessible with the demo, including vehicle speed, location, fuel level, time, ignition, and more.

Part of the attributes Otonomo provides are enrichments - data-driven attributes that are generated using a mix of attributes. In this demo service, you'll find enriched locations attributes such as vehicle country, City, and more.

For more information on your service, log into the consumer platform and head to the Aggregate tab.

What APIs are available in the trial?

With your demo service, you can fetch historical data using the following APIs:

  1. Raw Data : provides historical data points from the multiple simulated vehicles available in the trial.
  2. Aggregated Trips Data : provides aggregated data on the various trips the vehicles in Italy have driven.
  3. Trip Points: provides the data points from selected trips vehicles have driven.

You may generate up to 10 CSVs per day with your trial service.

Accessing Aggregated Historical Data

The Aggregated Data APIs are asynchronous and are generated in the background. As a result, the data is not provided in the response body of the API. The process of acquiring historical data is described below:

  1. Obtain a General Access Token
  2. Request Predefined Historical Data
  3. Check the Status
  4. Download When Ready

Step 1: Obtain a General Access Token

Otonomo utilizes an OAuth2 protocol in order to authenticate data consumers. Obtaining proper authentication is required to access historical data from Otonomo's API.

Authentication is given in the form of a token and is inputted as a header within each API requests. Each token can be used for 24 hours. Once this time is up, you will need to request a new token.

Use your credentials within the General Access Token API to obtain your token. You can find your Client ID and Client Secret at the top of the service page.

Request

curl https://auth.otonomo.io/oauth/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&audience=https://api.otonomo.io&client_id={client_id}&client_secret={client_secret}'

The response of the request will include an access token. This token is needed to access historical data.

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5UTkZORGxHT0VJeE5qZzNNVUkxUmpJMVJUZEJPRE15UlVVM05VTTJO",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Step 2: Request Predefined Historical Data

Request

In order to cater the API to your specific demo account, the path parameters in the request URL must reflect your information. Static information presented in {} within the endpoint must be changed to your account information.

You can find your consumer and service name by logging into Otonomo's Consumer Platform. The consumer name is located at the top, right corner of the page and the service name is located at the middle, left side of the page.

The General Access Token, as well as the request body format, must be included as a header in each API request. The request body parameters should be provided in the format described within the header.

Header
Description

authorization

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5UTkZORGxHT0VJeE5qZzNNVUkxUmpJMVJUZEJPRE15UlVVM05VTTJO

content-type

application/json

curl --request POST \
  -H 'Authorization: Your_token' -d 'body data' \
  --url  https://api.otonomo.io/api/consumer/{consumer_name}/service/{service_name}/reports/AnonymousHistoricalRawData
curl --request POST \
  -H 'Authorization: Your_token' -d 'body data' \ 
  --url https://api.otonomo.io/api/consumer/{consumer_name}/service/{service_name}/reports/AnonymousHistoricalTripsData

There are several request body params that can be used to filter what data you'd like to access within Historical Raw Data or Trips Data:

Parameter
Trial Limit
Required

start_datetime

The starting day from which data should be provided.

The starting period cannot precede "2019-01-14 00:00:01".

Yes

end_datetime

The date from which data will no longer be provided.

The ending period cannot proceed "2019-01-20 23:59:59"

Yes

country_code

The country code of Italy, "IT"

No

cities

Try any city in Italy

No

Polygon

A list of lists comprised of dictionaries representing each point (lon, lat) in a polygon. The country_codes filter is required when using this parameter.

No

cars_limit

The maximum number of cars that should be returned.

No

Here are some example request body parameters that reflect the data available in the trial service:

{  
   "start_datetime":"2019-01-20 00:00:00",
   "end_datetime":"2019-01-20 00:01:00"
}
{
  "start_datetime":"2019-01-20 00:00:00",
  "end_datetime":"2019-01-20 00:01:00"
  "country_codes": [
    "IT"
  ],
  "cities": [
    "Rome"
  ]
}
curl --request POST \
  -H 'Authorization: Your_token' -d 'body data' \
  --url https://api.otonomo.io/api/consumer/{consumer_name}/service/{service_name}/reports/TripsPoints

There is only one request body parameter for Trip Points: trip_id.

Input the trip_id for each trip you would like to receive more information on.

Here is an example of how your request body should be formatted. Just copy & paste the relevant trip_id. The trip_id can be found in the CSV file of Trip Data.

{
  "trip_ids": [
    "b54c8e8cce43afb53f66b99a069d69784583218aab9c7fb4",
    "b22d8e7dde43afz88f66m71a069d6998a683026aab9c7gt7"
  ]
}

Response

The response for each request will display a request_id number. This number is used to acquire the actual data via the Report Status endpoint.

{
  "report_status": "Ongoing",
  "request_id": 1945
}

Step 3: Check the Status

As the reports are asynchronous, they might take several minutes to create.

You can check the status of your report through the Consumer Platform or through the Historical Data APIs.

If the report is complete, you will receive a link to download the report as a CSV file. If the report is not complete, it is either still being created ("ongoing") or has failed to be created ("failed").

In order to retrieve the actual report via API, input the request id as a path parameter to distinguish which report you'd like to obtain.

curl --request GET \
  --url https://api.otonomo.io/api/consumer/{consumer_name}/service/{service_name}/reports/requests/request_id

The response will indicate the status of the report.

{
  "id": 1945,
  "report": 29,
  "status": "Completed",
  "result_url_list": {
    "part-00000-17f7c63d-c602-4b80-a371-3b567b9c67f6-c000.csv": "https://prod-otonomo-reports.s3-accelerate.amazonaws.com/1358/part-00000-17f7c63d-c602-4b80-a371-3b567b9c67f6-c000.csv?AWSAccessKeyId=AKIAJNZTR6WDPJLBQR6Q&Signature=qldjAbMkVxrp8l5vpj6bW4QIi6E%3D&Expires=1530166753"
  }
}
{
  "id": 1945,
  "report": 29,
  "status": "Ongoing",
  "result_url_list": null
}
{
  "id": 1945,
  "report": 29,
  "status": "Failed",
  "result_url_list": null
}

Step 4: Download

The output presented in the response body will be a downloadable link to a CSV file. Simply copy the link provided into any web browser and click enter. The report will begin to download automatically.

What's Next?

Want to get real-time anonymized or driver-specific data? Contact us at [email protected]

Aggregated Data Demo Service


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.