shell

Introduction

API Base URL

https://api.automatic.com/

We provide three APIs for interacting with Automatic data.

  1. REST API - lets your application request data from Automatic.
  2. Real-time Event API - sends event data to your application via websockets or pushes event data to a registered URL.
  3. Streaming API - provides direct access to the hardware via a subset of ELM327 over bluetooth for iOS or Android apps.

The REST API is considered our source of truth. The Real-time Event API cannot guarantee the same level of reliability for reasons described in the relevant section of this document.

This documentation is organized as a single page application so that you can search across all content in one place.

Authentication

Example Request Showing Access Token

curl "https://api.automatic.com/user/me/" -H "Authorization:Bearer {access token}"
curl uses the -H flag to add a header to the request. Identifying the header as “Authorization:Bearer” followed by a valid access token will give you access to the requested data. The process for obtaining access tokens is detailed in the Authorization section below.

You must authenticate for all requests on the Automatic APIs. Additionally, all API requests must be made over HTTPS. Calls made over plain HTTP will fail.

OAuth2 is required to authenticate.

After registering an application, you will authenticate to obtain an access token for a given user. To accomplish this, you will need to use your application’s Client Id and Client Secret. Both of these are available in the Developer Apps Manager along with a formatted Authorize URL and access token CURL request.

Application Modes

Development Mode Limits:

25 Access Tokens

When registering an application with Automatic, it will initially be put into Development Mode. This limits the application to 25 access tokens, which is meant to be enough for basic development.

Production Mode:

No Limits
Subject to usage review

When you reach 25 valid access tokens, your app will get an error parameter with the value access_denied in the redirect URL when a new user tries to log in.

When you would like to switch to Production Mode (unlimited users), you can request a review in the Developer Apps Manager and we will review the application's needs. Once we have verified proper use of user data and APIs, we can whitelist your application for production.

Scopes

Example OAuth Initial Request Showing Scopes

curl https://accounts.automatic.com/oauth/authorize \
  -d "client_id={your client_id}" \
  -d "response_type=code" \
  -d "scope=scope:trip%20scope:location%20scope:vehicle:profile%20scope:vehicle:events"
When taking a user through the OAuth flow, you will specify the scopes that you want them to authorize in the parameters of the Authorize URL. Note: your app must have these application-level scopes for you to be able to request them as token-level scopes.

Scopes specify what rights your application has for data access. Each API endpoint has certain scope requirements. A user must have authorized these scopes for your application in order for the endpoint to respond with the data you request. If you are missing a required scope, an API request will return a valid JSON object without the portion of data requiring that scope. If you are missing all required scopes for an API request, it will return an empty JSON object.

There are application-level scope rights and token-level scope rights. Token-level scope rights are what determine whether your requested data will be returned. Token-level scopes are issued per auth token based on the parameters you pass in a user’s OAuth flow. Requested token-level scopes may vary from one token to the next, though this is not common in practice.

App-level scope rights are given at the application level. They govern the maximum set of scopes you are allowed to ask a token to be granted during a user’s OAuth flow. You may not ask a token to have a scope unless you have the app-level rights for that scope. Adding an application level scope will not affect tokens issued beforehand: the tokens will still be valid and will not have any way to get the new scope. Removing an application-level scope will invalidate any tokens already issued which have the removed scope. Management of application-level scopes happens in the Developer Developer Apps Manager

When registering an application with Automatic, you will select the application-level scopes to which you'd like access. These are given without question while the application is in Development Mode. During a Production Mode review, we may require the removal of scopes for which there is not an explicit need given the application's stated purpose.

When sending a user through the OAuth workflow, the scope parameter of your request must include the scopes you would like for that particular user token. This can be a subset of your apps scores, but may not include any scopes for which your app does not have rights. The requested scopes will be explicitly presented to users on the Automatic authorize form.

Here are the scopes currently available:

Scope NameDescription
scope:publicAccess to public information about user.
scope:user:profileAccess to user's profile (i.e. first_name, last_name, email).
scope:locationAccess to historical location. Applies to all events.
scope:current_locationAccess heartbeat location updates in real-time during a drive.
NOTE: this scope governs one very special event only, location:updated, and is only needed for a narrow class of apps. This event is only supported via websockets. Importantly, this scope is NOT needed for location information in trips or vehicle events.
scope:vehicle:profileAccess to vehicle information (i.e. year, make, model). Applies to all events.
scope:vehicle:eventsAccess to vehicle events details (i.e. hard_brake, hard_accel).
scope:vehicle:vinAccess to VIN (Vehicle Identification Number).
scope:tripAccess to trips that are visible to a user.
NOTE: the Trip endpoint requires many scopes to get the complete set of data. scope:trip alone does not give very much, but is required to get anything in the Trip object.
scope:behaviorAccess to user's driving behavior summary stats.

OAuth Workflow

OAuth Production Workflow

1. Link user to the authorize URL
2. We redirect to your application’s redirect URL with a `code`
3. POST `code`, `client_id`, and `client_secret` to access token URL
4. Store `access_token` and `refresh_token`
5. Redirect user to your application’s start point

Some of the Automatic wrapper libraries handle the details of OAuth2 for you, and many third-party OAuth2 libraries exist for virtually every language. The workflow below describes the process in its raw form.

During development, it may be easiest to obtain the access token for your own user account and hardcode it into your application. This would need to be removed and replaced with a proper workflow before pushing any application into production or having multiple users. Obtaining an access token for your own user account is simplified with tools in the Developer Apps Manager.

####1. LINK OR REDIRECT USERS TO THE AUTOMATIC AUTHORIZE URL

EXAMPLE AUTHORIZE URL AS STRING (formatted for our sample Tripviewer app)

https://accounts.automatic.com/oauth/authorize/?client_id=Yqsysr3zkbAvDTkMRdzB&response_type=code&scope=scope:trip%20scope:location%20scope:vehicle:profile%20scope:vehicle:events

RESPONSE

HTML Authorization Page to be rendered in browser.

This must be properly formatted for your application and will return a permissions screen for the user to authorize. For convenience, a formatted authorize URL including your client_id is provided for each application in the Developer Apps Manager.

Base URL

GET https://accounts.automatic.com/oauth/authorize/

Parameters

NameDescription
client_idRequired stringThe client ID for your application
scopeRequired stringURL-encoded, space-separated list of scopes that your application needs. Read more about scopes in the Scopes section.
response_typeRequired stringValue should be "code"
stateOptional stringAn unguessable random string. It is used to protect against cross-site request forgery attacks.

####2. WE REDIRECT TO YOUR REDIRECT URL

GET REQUEST SENT TO YOUR APP REDIRECT URL

https://example.com/redirect?code=AUTH_CODE&state=STATE

When the user authorizes access, Automatic will make a GET request to the Redirect URL you have specified for you application. A temporary Authorization Code will be included in the code parameter.

If you included a value in the optional state parameter, this will be included as well. Should the state value not match your original, the request has been created by a third party and the process should be aborted.

####3. MAKE POST REQUEST TO OBTAIN ACCESS TOKEN

EXAMPLE REQUEST FOR ACCESS TOKEN

curl -X POST https://accounts.automatic.com/oauth/access_token \
  -d "client_id=[YOUR_CLIENT_ID]" \
  -d "client_secret=[YOUR_CLIENT_SECRET]" \
  -d "code=[YOUR_CODE_FROM_STEP_1]" \
  -d "grant_type=authorization_code"

RESPONSE

{
  "access_token": "PrBfQ1sp534wDaaU7tbBTVObqj83QUekVemnEsXs",
  "expires_in": 31535999,
  "scope": "scope:vehicle:events",
  "refresh_token": "3ddcc6ec0cb968a10fb235ecf90f534244d2b759",
  "token_type": "Bearer"
}

Your application needs to then take the code returned in the previous step and POST that along with your Client Id and Secret to the access token URL. A formatted CURL example is presented in the sample pane.

HTTP Request

POST https://accounts.automatic.com/oauth/access_token

Parameters

NameDescription
client_idRequired stringThe client ID for your application
client_secretRequired stringThe client secret for your application
codeRequired stringThe code you received as a response to Step 1.
grant_typeRequired grant_typeValue should be "authorization_code"

####4. CAPTURE AND STORE ACCESS TOKEN The above request will return an access token for the given user, as JSON, which you can now use in a request header to access data from the Automatic REST API. This access token needs to be stored for future use if you would like the user to have ongoing access. If you have supplied Automatic with a Webhook URL for your application, we will now start posting events for that user to the URL as they happen.

A refresh token is delivered in the same response. It is best practice to save this for when you need to renew credentials. For most Automatic platform apps, tokens are good for one year.

####5. REDIRECT USER AND MAKE API CALLS USING ACCESS TOKEN You should now redirect the user to the appropriate page to use your application, as in the example provided. Details on making specific calls are covered in the rest of this document.

####6. USE THE REFRESH TOKEN TO GET A NEW ACCESS TOKEN

EXAMPLE REQUEST TO REFRESH ACCESS TOKEN

curl -X POST https://accounts.automatic.com/oauth/access_token/ \
  -d "client_id=[YOUR_CLIENT_ID]" \
  -d "client_secret=[YOUR_CLIENT_SECRET]" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=[YOUR_REFRESH_TOKEN]"

RESPONSE

{
  "access_token": "PrBfQ1sp534wDaaU7tbBTVObqj83QUekVemnEsXs",
  "expires_in": 31535999,
  "scope": "scope:vehicle:events",
  "refresh_token": "3ddcc6ec0cb968a10fb235ecf90f534244d2b759",
  "token_type": "Bearer"
}

If you save the refresh_token that is returned with the access_token in step 3 above, you can use it to obtain a new access_token at any time in the future.

HTTP Request

POST https://accounts.automatic.com/oauth/access_token

Parameters

NameDescription
client_idRequired stringThe client ID for your application
client_secretRequired stringThe client secret for your application
grant_typeRequired grant_typeValue should be "refresh_token"
refresh_tokenRequired stringThe refresh_token you received as a response to Step 3.

Real-time Events

You can consume real time events in three ways.

Websocket API
You open a websocket connection using socket.io to get a real-time stream of events, including real-time location.

Webhook API
Your application can receive push notifications as HTTP POST requests of certain events. This enables your application to passively listen for and respond to triggers.

Android SDK
Your application binds to the Automatic Android app via our Android SDK and receives real-time events via a simple callback interface.

Using Websockets

Automatic Websocket URL

https://stream.automatic.com?token={your client_id}:{your client_secret}

You can connect to the Websocket API at https://stream.automatic.com by passing a token parameter in the query string that has your Automatic Client ID and Automatic Client Secret separated by a colon (:).

For example, if your client ID is 1234 and your client secret is 9876, the url you should connect to is https://stream.automatic.com?token=1234:9876.

EXAMPLE Socket.io listener in Javascript

var io = require('socket.io-client')

var socket = io('https://stream.automatic.com?token={your client_id}:{your client_secret}')

// Listen for `trip:finished` event
socket.on('trip:finished', function(eventJSON) {
  console.log('Trip Finished', eventJSON);
});

// Handle `error` messages
socket.on('error', function(errorMessage) {
  console.log('Error', errorMessage);
});

You should use the socket.io library for the language of your choice.

Using socket.io, you should listen for any event type that your application needs and listen for error messages.

Receiving Webhooks

To use the Automatic Webhook API, you must register a Webhook URL for your application in the Developer Apps Manager and have user tokens with authorization for the appropriate scopes.

Once this is in place, we will begin sending all appropriate events to your registered URL. Events are sent as HTTP POST requests where the request body is a JSON object. Each JSON object will contain a type parameter which will match one of the event types listed below.

Timeliness & Delivery

Webhooks, by nature, do not guarantee delivery. Our implementation does not guarantee timeliness either. If your application requires 100% certainty about user data, we suggest also using the REST API and poll periodically and backfill any missed events. For most practical matters, however, the Websocket API and Webhook API should be more than sufficient.

Timeliness Caveats
We will generally try to send an event when that event happens, in real-time. But in some cases events may fire much later, e.g. when an active internet connection is not available in an underground parking lot. In that case, a trip is uploaded to our servers only well after the trip took place. The associated trip:finished event would only be sent once our server received the trip, which could be hours or days later.

If a user hasn't uploaded data for a while, we may end up sending many trip:finished events in rapid succession. It is imperative that your application inspect the timestamp of each event and react appropriately. In the case of trip:finished, e.g., this would be the embedded trip object's started_at and ended_at fields.

False Negative Caveats
Other events, however, may never be sent via webhooks/websockets at all under certain situations, where the time-window of sending them no longer makes sense. ignition:on is one such event. If our servers don’t receive an event within a few minutes of it happening, and instead receive it hours or days later, we will not attempt to send it via a webhook or over a websocket. Specific time limits are stated in each event’s description.

False Positive Caveats
There are some drive events which will be sent via a webhook or over a websocket in real-time but which will be later filtered out by our trip processing algorithm and thus not make it to the REST object. The events which are filtered out are considered invalid for a variety of reasons and should not count against a behavioral assessment.

Delivery Caveats
When we attempt to send an event, we have no way to guarantee that your application will receive it. We also cannot guarantee that your application will receive an event only once. Be sure to build in de-duplication logic into your application to ensure that events are not duplicated on the same trip. See the Expected Response section for more info.

Privacy

For applications using the Webhook API, we require that the webhook URL use HTTPS because private user information will be transmitted. Users trust your application with this information, and Automatic expects you not to violate this trust. We require that your application not retransmit insecurely, retain indefinitely or share with 3rd parties any data sent via the Automatic Webhook API.

The Websocket API only accepts HTTPS connections.

Expected Webhook Response

Your application should respond with a 200-range HTTP status code to acknowledge successful receipt of a webhook. If your application responds with a non 200-range HTTP status code, we will assume that your application did not receive the webhook.

Webhook Retries

We retry webhook requests up to three times, at ten second intervals.

Webhook Discrepancies from REST

There are a few notable inconsistencies between the data retreived via the REST API and the Webhook API that are important to understand. Note that these only apply to the Webhook API, not the Websocket API

EXAMPLE NAMES, UNITS DISCREPANCY

//Webhook
{
  "fuel_volume_gal": 1.0
}
// REST
{
  "fuel_volume_l": 3.78
}

Units
Webhook data fields are in mostly imperial units (mpg, gallons) whereas REST is in mostly metric (kmpl, liters). Each data field is explicit in its naming — e.g. fuel_volume_gal vs fuel_volume_l. This is a vestige of webhooks being developed alongside our now legacy REST v1 API.

Field names
Field names for the same concept may differ, including all fields with distance or volume units, as noted.

EXAMPLE TIMESTAMPS DISCREPANCY

Webhook: end_time: 1427425622890
REST: ended_at: "2015-03-27T03:07:02Z"
REST query param: /trip/?started_at__gte=1427425622

Timestamps
Automatic Webhooks use timestamps as epoch milliseconds (NOT seconds). For example: 1427425622890, which is Fri, 27 Mar 2015 03:07:02 GMT.

Automatic Websockets and the REST API use timestamps formatted as a subset of ISO 8601 which uses millisecond precision, and includes the 'Z' suffix for the UTC timezone. For example: 2015-03-27T03:07:02.123Z which is Fri, 27 Mar 2015 03:07:02 GMT.

User v2_id
There are two notions of a user id included in the user object of each webhook: id and v2_id. This is because our REST v1 and REST v2 use different schemes for a user's unique identifier and we wanted to make webhooks compatible with both. REST v2 ids will always start with U_, whereas v1 ids are more like 2fcd8161801e95d1e615.

Historically, webhooks used the v1 id format and simply called it id within the user object. To avoid a breaking chance, we added the v2 id as v2_id.

User IDs can be retreived with the appropriate REST call to the user path. We are actively working on fixing these inconsistencies, but do not plan on making breaking changes without informing you first.

EXAMPLE USER OBJECT IN WEBHOOKS

{
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25" // use this to match with REST
  }
}

EXAMPLE USER OBJECT IN WEBHOOKS
In webhooks user objects and vehicle objects are presented in full when they are parts of an event. In REST those concepts will instead be presented as URIs to the objects.

Trip Finished

EXAMPLE TRIP FINISHED OBJECT WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "trip:finished",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "trip" {
    // Trip Object (matches REST API)
  }
}

EXAMPLE TRIP FINISHED OBJECT WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "trip:finished",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "trip": {
    "id": "T_8e7b567626c26695",
    "start_location": {
      "name": "Ashbury St, SF, CA",
      "display_name": "Home",
      "lat": 37.7692903,
      "lon": -122.4465469,
      "accuracy_m": 5,
      "ts": 1383448450201,
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "street_name": "Ashbury",
      "street_number": "464"
    },
    "start_time": 1383448450201,
    "start_time_zone": "America/Los_Angeles",
    "end_location": {
      "name": "5th St, SF, CA",
      "display_name": "Work",
      "lat": 37.78270046281092,
      "lon": -122.4064556183999,
      "accuracy_m": 100,
      "ts": 1383449950201,
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "street_name": "5th",
      "street_number": "201"
    },
    "end_time": 1383449950201,
    "end_time_zone": "America/Los_Angeles",
    "path": "uioeFxycjVxDMvAGBjATlJXrLaIZHvCFhCHpCaI^i@@",
    "distance_m": 6573.416666666661,
    "hard_accels": 0,
    "hard_brakes": 1,
    "duration_over_80_s": 0,
    "duration_over_75_s": 2,
    "duration_over_70_s": 3,
    "fuel_cost_usd": 1.0428111627932486,
    "fuel_volume_gal": 0.2465857561582522,
    "average_mpg": 16.56434586845349,
    "idling_time_s": 78.47,
    "score_events": 33.67,
    "score_speeding": 40.19,
    "city_fraction": 0.45,
    "highway_fraction": 0.55,
    "night_driving_fraction": 0
  }
}

Description

A trip has been completed.

Scopes

Requires scope:trip scope.

For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent after a trip is completed and processed by Automatic. In a case of trips being uploaded after a time delay, we may fire events for multiple trips at once. Thus, you should not consider receipt of the trip:finished webhook as an indicator that the trip has just recently completed, although that will be the case most of the time. Instead, if your use of this data is based on the time the event happened, you should look at the timestamps in the trip objects started_at and ended_at fields.

Differences between Webhooks and Websockets

The trip field in trip:finished events sent over webhooks does not match the format of the REST API or the events sent over websockets.

Webhook trip:finished fields are documented above.

Websocket trip:finished events match the fields from the Trip REST API.

Timeout limit

This event will fire when it is received by our server. There is no timeout.

Note on path data

Trip paths are stored in a format called Encoded Polyline. Polyline is a small javascript library that can encode and decode this data into an array of lat/long points. Alternatively, you can use this web-based utility to do this manually. If building an application using Google Maps, you can use encoded polylines natively without conversion.

In cases where no GPS signal was available during the trip, path may be returned as null.

Ignition On

EXAMPLE IGNITION:ON WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "ignition:on",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

EXAMPLE IGNITION:ON WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "ignition:on",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

Description

A vehicle has been turned on.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location, scope:vehicle and scope:behavior are also required. See API Objects for more details.

Trigger

Sent when vehicle ignition is turned on.

This event is sent in real-time and requires a working internet connection to be present and connected.

This event is useful for triggering automated services that need to respond in realtime to being in the car. If the client (the Automatic smartphone app) is not connected to the Automatic adapter at the time of ignition but connects shortly thereafter, the ignition:on event will be sent when said connection is established. The client, in turn, will attempt to send the event to our servers, retrying up to five times at short intervals, after which it will give up. In practice, if there is not a working connection present in this trip, event will never be sent via webhook or websocket.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Ignition Off

EXAMPLE IGNITION:OFF WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "ignition:off",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

EXAMPLE IGNITION:OFF WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "ignition:off",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

Description

A vehicle has been turned off.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when vehicle ignition is turned off. This event is useful for triggering automated services that need to respond in realtime to parking or finishing a trip.

The same delivery rules as ignition:on apply. Additionally, some cars do not indicate to us explicitly when the ignition is turned off and in those cases we infer from other signals, which may add a time delay of one minute for confirmation of the inference.

Whether inferred or not, ignition:off will come sooner than trip:finished will — generally the gap between the two is under 30 seconds, but in some cases can be longer.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Speeding

EXAMPLE NOTIFICATION:SPEEDING WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:speeding",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "velocity_kph": 112.654
}

EXAMPLE NOTIFICATION:SPEEDING WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "notification:speeding",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "speed_mph": 70
}

Description

A speed threshold has been crossed.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent after a "velocity exceeded threshold" event occurs.

These events will be generated for exceeding each of 70, 75, and 80 MPH (miles per hour). They will be generated once per threshold crossing. To trigger the same threshold event, a user must dip 5 MPH below the threshold first. This is to avoid rapid re-crossings — e.g. hovering right between 69 and 70 MPH.

The same delivery rules as ignition:on apply.

Differences between Webhooks and Websockets

Webhook notification:speeding events include a speed_mph field which is the maximum velocity attained in miles per hour.

Websocket notification:speeding events include a velocity_kph field which is the maximum velocity attained in kilometers per hour.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Hard Brake

EXAMPLE NOTIFICATION:HARD_BRAKE WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:hard_brake",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

EXAMPLE NOTIFICATION:HARD_BRAKE WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "notification:hard_brake",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

Description

A hard brake event occurred.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when a hard braking event occurs.

Some events will be filtered out in post-trip processing. Hard brakes are determined in real-time with a basic algorithm that generates both the audio alerts on the adapter as well as the webhook/websocket events. The simple rule is a speed decrease of more than 11 km/h per second.

Once a trip is completed, these events are run through a more advanced algorithm. In that second pass, some of the events are deemed false-positives, or circumstantially explainable. In these instance, they will not be recorded into the ultimate REST objects, though the webhook/websocket events will have already fired.

Subsequent hard brakes within five seconds of the original will be disregarded.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Hard Accel

EXAMPLE NOTIFICATION:HARD_ACCEL WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:hard_accel",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

EXAMPLE NOTIFICATION:HARD_ACCEL WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "notification:hard_accel",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

Description

A hard acceleration has occurred.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when a hard acceleration event occurs.

Some events will be filtered out in post-trip processing. Similar to hard brake events, some hard accel events which fired as webhooks/websockets will be filtered out in post trip processing. Also, the simple definition is 11km/h per second acceleration.

Subsequent hard accels within five seconds of the original will be disregarded.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket will not be generated.

MIL On

EXAMPLE MIL:ON WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "mil:on",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "created_at": "2015-04-12T17:44:11.123Z"
    }
  ]
}

EXAMPLE MIL:ON WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "mil:on",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "start": 1383448450301
    }
  ]
}

Description

The MIL (check engine light) is on.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when an MIL (check engine light) comes on. MIL stands for malfunction indicator light, also known as the check engine light. This event will return an array of DTCs, or Diagnostic Trouble Codes.

Often, when a check engine light comes on, there are more than one DTCs contributing to the event. dtcs is an array and can include more than one trouble code. Also, more than one mil:on events may be fired before an mil:off event if additional DTC codes come on after the initial mil:on event.

Differences between Webhooks and Websockets

Webhook mil:on events have a start field with timestamp as epoch milliseconds.

Websocket mil:on events have a created_at field with timestamp in ISO8601 format.

Timeout limit

This event will fire when it is received by our server. There is no timeout.

MIL Off

EXAMPLE MIL:OFF WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "mil:off",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "created_at": "2015-04-12T17:44:11.123Z"
    }
  ],
  "user_cleared": true
}

EXAMPLE MIL:OFF WEBHOOK

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_ffd955ba63db5c25"
  },
  "type": "mil:off",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "ts": 1383448450201
  },
  "vehicle": {
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "start": 1383448450301
    }
  ],
  "user_cleared": true
}

Description

The MIL (check engine light) is off.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when an MIL (check engine light) goes off. Note that dtcs is an array and can include more than one trouble code, if more than one contributed to the MIL event.

Differences between Webhooks and Websockets

Webhook mil:off events have a start field with timestamp as epoch milliseconds.

Websocket mil:off events have a created_at field with timestamp in ISO8601 format.

Timeout limit

This event will fire when it is received by our server. There is no timeout.

Location Updated

EXAMPLE LOCATION:UPDATED WEBSOCKET

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.automatic.com/user/U_ffd955ba63db5c25/"
  },
  "type": "location:updated",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location" : {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.automatic.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

Description

A ping of vehicle location

Scopes

Requires scope:current_location scope. For access to all fields scope:vehicle is also needed.

Trigger

Sent every minute during a drive.

Differences between Webhooks and Websockets

This event is only available via websockets.

Rest API

Base URL

https://api.automatic.com/

The Automatic REST API allows your application to request data and make limited writes to a user account.
As previously noted, all calls must be authenticated with an Automatic user access token.

Device

Deprecated in favor of /user/me/device/ APIs.

List my devices

Definition

GET /device/

Example Request




curl  "https://api.automatic.com/device/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "_metadata": {
    "count": 1,
    "next": null,
    "previous": null
  },
  "results": [
    {
      "id": "4aa9b556d5072af84efcb103",
      "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/device/4aa9b556d5072af84efcb103/",
      "version": 2,
      "direct_access_token": "authticket 1 4aa9b556:d5072af8:4efcb103 1 e6d9347e5341ac0a326a 192:8ac04c19:2cab9102:20ce85ef:b7c50475:a1efe6e3:6beb4fc2 1604786476 899dd3350aa9453b709b0d9c21ea4db2e00c1ff604e4a3f24d3c9b65a5dc9543a1ec49f78445f7b27ce291b1aefc75ce221e94cf1b821b2c31157e0b9ef31a7b6b5ca102792392be124278eaa0d3f022f185153b65d548dc7619261a13f20c96dc7c9c5faa8097e3e8c4171f3bed116329a3447eba93ec588884410b92e08068",
      "app_encryption_key": "4b5199c1899da2aa98baeac4af3e078e"
    }
  ]
}

Returns an array of DeviceUserRelationship Objects

Query Parameters

ParameterDescription
device__serial_number
Optional, default is null
(STRING) Serial Number
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

Get a single device's information

Definition

GET /device/{device_id}/

Example Request


curl  "https://api.automatic.com/device/{device_id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "id": "4aa9b556d5072af84efcb103",
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/device/4aa9b556d5072af84efcb103/",
  "version": 2,
  "direct_access_token": "authticket 1 4aa9b556:d5072af8:4efcb103 1 e6d9347e5341ac0a326a 192:8ac04c19:2cab9102:20ce85ef:b7c50475:a1efe6e3:6beb4fc2 1604786476 899dd3350aa9453b709b0d9c21ea4db2e00c1ff604e4a3f24d3c9b65a5dc9543a1ec49f78445f7b27ce291b1aefc75ce221e94cf1b821b2c31157e0b9ef31a7b6b5ca102792392be124278eaa0d3f022f185153b65d548dc7619261a13f20c96dc7c9c5faa8097e3e8c4171f3bed116329a3447eba93ec588884410b92e08068",
  "app_encryption_key": "4b5199c1899da2aa98baeac4af3e078e"
}

Returns a DeviceUserRelationship Object

Tag

Tags are classifiers for users' trips. They can be applied in Automatic apps, partner apps, or via script using the API. At the moment, there is only one tag supported: business. Attempts to write other tags will fail until further notice.

The various endpoints under the tag model are not the way to fetch trips with a tag, nor the way to tag trips.The former is a param on the /trip/ endpoint, and the latter is an endpoint unto itself at /trip/{sid}/tag/

List of tags

Definition

GET /tag/

Example Request




curl  "https://api.automatic.com/tag/?limit=1" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "_metadata": {
    "count": 2,
    "next": "https://api.automatic.com/tag/?limit=1&page=2",
    "previous": null
  },
  "results": [
    {
      "tag": "business"
    }
  ]
}

Returns an array of Tag Objects

Provides a listing of all tags on a user account. It is useful for building interfaces for a users to choose from existing tags.

Query Parameters

ParameterDescription
tag__istartswith
Optional, default is null
(STRING) Tag prefix filter. Multiple tags can be specified by comma separating them. That will perform an OR search. AND search is not possible at this time.

Note: the "__" is a double underscore. This is a django convention.
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

Get a specific tag

Definition

GET /tag/{slug}/

Example Request


curl  "https://api.automatic.com/tag/{slug}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "tag": "business"
}

Returns a Tag Object

Trip

A trip is created when a vehicle is understood to have one full cycle of ignition:on to ignition:off. In some vehicles, these signals must be inferred.

Trips are the most commonly used objects in the API. They contain a wealth of metadata about a vehicle's usage history and a user's behavior.

At present, one write is possible: adding a tag to a trip.

The mobile apps have a feature that allows combining of trips that happened within 15 minutes of each other. This merge is applied on the apps' frontend only and does not affect the REST objects, which would show the multiple 'segments' as distinct and unrelated entities.

Trips must have a minimum distance of 10 meters or they will be discarded as invalid.

Get a specific trip

Definition

GET /trip/{id}/

Example Request


curl  "https://api.automatic.com/trip/{id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "url": "https://api.automatic.com/trip/T_5ecb5afa2422d3d8/",
  "id": "T_5ecb5afa2422d3d8",
  "driver": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
  "user": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
  "started_at": "2015-03-20T00:53:43.969000Z",
  "ended_at": "2015-03-20T01:43:36.738000Z",
  "distance_m": 16219.4,
  "duration_s": 2992.8,
  "vehicle": "https://api.automatic.com/vehicle/C_9aa0f0e09383666c/",
  "start_location": {
    "lat": 33.95235,
    "lon": -118.38511,
    "accuracy_m": 3.9
  },
  "start_address": {
    "name": "5862 Arbor Vitae Street, Los Angeles, CA 90045, USA",
    "display_name": "Arbor Vitae St, LA, CA",
    "street_number": "5862",
    "street_name": "Arbor Vitae St",
    "city": "LA",
    "state": "CA",
    "country": "US"
  },
  "end_location": {
    "lat": 34.08308,
    "lon": -118.3659,
    "accuracy_m": 9
  },
  "end_address": {
    "name": "667 North Crescent Heights Boulevard, Los Angeles, CA 90048, USA",
    "display_name": "N Crescent Heights Blvd, LA, CA",
    "street_number": "667",
    "street_name": "N Crescent Heights Blvd",
    "city": "LA",
    "state": "CA",
    "country": "US"
  },
  "path": "_kfnE|aqqUAka@?aFBmDAuB}B?eN@wH@oL?iB@{@C[MUOOO}AcCaAsBUm@qD}LkEgOkBp@uAVsA?e@Ei@I{@WeBk@cBa@a@GmBGsBIkAEm@?}B?QLiECeDBcTAeC?cB@OKyA?yF?wD?qBD_FLyK\\sTr@uBByACyAM}@MkAYo@QeGuBQM{Ai@qBq@uCs@gB[oBQ{BEeD?_CJ{K|@_Ff@mAXuBx@mVdLaGfDyBl@_BT}DVkDPsCHwVi@aBB_AH}AZoBn@mFdBgBTm@DsA@m@AoAOiAUmA_@oHeDuBy@iAWcAMoAEqCCG?QH_BCuFKgHUgIMaEM_KQcGKo@Wc@E{@QyBi@_IoCuJkDgEuA_Cy@{CcAm@M_@IeBEoBRiA\\kB|@iDhBk@R}@Tu@DoA?UCgBk@{Bw@mCw@_Bo@eIgCcD}@sHwAaNaCeEs@sA@mBEgASgOmFeLcEgFgBgBs@qMmF{DcBeBs@qAc@[E}B?eACuI?eD?KjB{@fPaDYyE]_@Ao@Fe@PuDzBeC~Aq@Vi@Hm@BqD?_RHoC?w_@AmHB",
  "fuel_cost_usd": 1.92,
  "fuel_volume_l": 2.1,
  "average_kmpl": 7.7,
  "average_from_epa_kmpl": 9.4,
  "score_events": 47.7,
  "score_speeding": 50,
  "hard_brakes": 0,
  "hard_accels": 1,
  "duration_over_70_s": 0,
  "duration_over_75_s": 0,
  "duration_over_80_s": 0,
  "vehicle_events": [
    {
      "type": "hard_accel",
      "lat": 33.97642,
      "lon": -118.37013,
      "created_at": "2015-03-20T01:06:36.547000Z",
      "g_force": 0.3374651
    }
  ],
  "start_timezone": "America/Los_Angeles",
  "end_timezone": "America/Los_Angeles",
  "city_fraction": 1,
  "highway_fraction": 0,
  "night_driving_fraction": 0,
  "idling_time_s": 37,
  "tags": [
    "business"
  ]
}

Returns a Trip Object

Provides a single trip's details.

Note On Fuel Cost

Fuel cost of a trip is based on the best fuel price information we have for a vehicle at the time of the trip, including the fuel grade selected by a user preference.

In the United States, fuel price is retrieved automatically based on location at the time of fillup. If a car does not report its fuel level, then each trip's cost will be estimated using prevailing local prices.

Outside the United States, our fuel costing will currently provide unreliable results. This will be improved in the future. For the time being, it is recommended to use fuel volume as the reliable metric instead.

Note On Path Data

Trip paths are stored in a format called Encoded Polyline. Polyline is a small javascript library that can encode and decode this data into an array of lat/long points. Alternatively, you can use this web-based utility to do this manually. If building an application using Google Maps, you can use encoded polylines natively without conversion.

In cases where no GPS signal was available during the trip, path may be returned as null.

NOTE: score_events and score_speeding are not fully implemented as of the time of this writing. Trips will return without those fields until it is implemented

Get a list of my trips

Definition

GET /trip/

Example Request









This query will look for trips that happened between Jan 1 and Feb 1, 2015 in a specific vehicle and with the business tag, returning 13 per page.
curl "https://api.automatic.com/trip/?started_at__gte=1426898108&ended_at__lte=1426916941&vehicle=C_9aa0f0e09383666c&tags__in=business&limit=5" \
-H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "_metadata": {
    "count": 5,
    "next": "https://api.automatic.com/trip/?limit=1&page=2",
    "previous": null
  },
  "results": [
    {
      "url": "https://api.automatic.com/trip/T_5ecb5afa2422d3d8/",
      "id": "T_5ecb5afa2422d3d8",
      "driver": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
      "user": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
      "started_at": "2015-03-20T00:53:43.969000Z",
      "ended_at": "2015-03-20T01:43:36.738000Z",
      "distance_m": 16219.4,
      "duration_s": 2992.8,
      "vehicle": "https://api.automatic.com/vehicle/C_9aa0f0e09383666c/",
      "start_location": {
        "lat": 33.95235,
        "lon": -118.38511,
        "accuracy_m": 3.9
      },
      "start_address": {
        "name": "5862 Arbor Vitae Street, Los Angeles, CA 90045, USA",
        "display_name": "Arbor Vitae St, LA, CA",
        "street_number": "5862",
        "street_name": "Arbor Vitae St",
        "city": "LA",
        "state": "CA",
        "country": "US"
      },
      "end_location": {
        "lat": 34.08308,
        "lon": -118.3659,
        "accuracy_m": 9
      },
      "end_address": {
        "name": "667 North Crescent Heights Boulevard, Los Angeles, CA 90048, USA",
        "display_name": "N Crescent Heights Blvd, LA, CA",
        "street_number": "667",
        "street_name": "N Crescent Heights Blvd",
        "city": "LA",
        "state": "CA",
        "country": "US"
      },
      "path": "_kfnE|aqqUAka@?aFBmDAuB}B?eN@wH@oL?iB@{@C[MUOOO}AcCaAsBUm@qD}LkEgOkBp@uAVsA?e@Ei@I{@WeBk@cBa@a@GmBGsBIkAEm@?}B?QLiECeDBcTAeC?cB@OKyA?yF?wD?qBD_FLyK\\sTr@uBByACyAM}@MkAYo@QeGuBQM{Ai@qBq@uCs@gB[oBQ{BEeD?_CJ{K|@_Ff@mAXuBx@mVdLaGfDyBl@_BT}DVkDPsCHwVi@aBB_AH}AZoBn@mFdBgBTm@DsA@m@AoAOiAUmA_@oHeDuBy@iAWcAMoAEqCCG?QH_BCuFKgHUgIMaEM_KQcGKo@Wc@E{@QyBi@_IoCuJkDgEuA_Cy@{CcAm@M_@IeBEoBRiA\\kB|@iDhBk@R}@Tu@DoA?UCgBk@{Bw@mCw@_Bo@eIgCcD}@sHwAaNaCeEs@sA@mBEgASgOmFeLcEgFgBgBs@qMmF{DcBeBs@qAc@[E}B?eACuI?eD?KjB{@fPaDYyE]_@Ao@Fe@PuDzBeC~Aq@Vi@Hm@BqD?_RHoC?w_@AmHB",
      "fuel_cost_usd": 1.92,
      "fuel_volume_l": 2.1,
      "average_kmpl": 7.7,
      "average_from_epa_kmpl": 9.4,
      "score_events": 47.7,
      "score_speeding": 50,
      "hard_brakes": 0,
      "hard_accels": 1,
      "duration_over_70_s": 0,
      "duration_over_75_s": 0,
      "duration_over_80_s": 0,
      "vehicle_events": [
        {
          "type": "hard_accel",
          "lat": 33.97642,
          "lon": -118.37013,
          "created_at": "2015-03-20T01:06:36.547000Z",
          "g_force": 0.3374651
        }
      ],
      "start_timezone": "America/Los_Angeles",
      "end_timezone": "America/Los_Angeles",
      "city_fraction": 1,
      "highway_fraction": 0,
      "night_driving_fraction": 0,
      "idling_time_s": 37,
      "tags": [
        "business"
      ]
    }
  ]
}

Returns an array of Trip Objects

Provides a listing of trips that match the query parameters. An example with many parameters is provided in the code panel.

See note above about fuel cost.

See note above about path data format.

Query Parameters

ParameterDescription
started_at__lte
Optional, default is null
(INTEGER) Start time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8"="1431126000
started_at__gte
Optional, default is null
(INTEGER) Start time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
ended_at__lte
Optional, default is null
(INTEGER) End time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8"="1431126000
ended_at__gte
Optional, default is null
(INTEGER) End time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
vehicle
Optional, default is null
(STRING) Vehicle Filter
tags__in
Optional, default is null
(STRING) Tags Filter
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

Remove tag from a trip

Definition

DELETE /trip/{trip_id}/tag/{tag}/

Example Request



curl -X DELETE "https://api.automatic.com/trip/{trip_id}/tag/{tag}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{}

Returns a TripTag Object

Removes a TripTag from a Trip.

NOTE: TripTags removed via REST API may not be reflected in the Automatic mobile apps (iOS 2.x, Android 1.x) without a logout/login cycle. This is not ideal and proper synchronization will be addressed in future versions.

Get tag associated with trip

Definition

GET /trip/{trip_id}/tag/{tag}/

Example Request



curl  "https://api.automatic.com/trip/{trip_id}/tag/{tag}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "tag": "business",
  "created_at": "2015-03-19T21:39:49.333000Z"
}

Returns a TripTag Object

Returns a specific TripTag, which is the association of a Tag to a trip. Whereas the Tags are available as an array in a Trip, calling the specific TripTag object additionally provides the time a given tag was applied to a trip.

Tag a trip

Definition

POST /trip/{trip_id}/tag/

Example Request




curl -X POST "https://api.automatic.com/trip/{trip_id}/tag/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991" \
  -d tag="personal"

Example Response

{
  "tag": "personal",
  "created_at": "2015-03-19T21:39:49"
}

Returns a TripTagCreate Object

Creates a TripTag to apply a Tag to a Trip.

NOTE: Trips tagged via the REST API may not be reflected in the Automatic mobile apps (iOS 2.x, Android 1.x) without a logout/login cycle. This is not ideal and proper synchronization will be addressed in future versions.

User

User is the object representing an Automatic account holder. In practice this represents an owner or driver of a vehicle.

A user may have many vehicles (and a vehicle may have many users).

Get user information

Definition

GET /user/{id}/

Example Request


curl  "https://api.automatic.com/user/{id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "id": "U_de0cf1b496008d9b",
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
  "username": "user-1@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "email": "user-1@example.com"
}

Returns a User Object

Provides the basic account information about a user.

Although the endpoint format takes an arbitrary user_id, access tokens granted to external developers can only access the user account which generated them. For this reason, the term "me" is an alias for the user_id of the access token's user.

Get user profile information

Definition

GET /user/{user_id}/profile/

Example Request


curl  "https://api.automatic.com/user/{user_id}/profile/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/profile/",
  "user": "https://api.automatic.com/user/U_de0cf1b496008d9b/",
  "date_joined": "2015-05-05T12:05:06.543641Z",
  "tagged_locations": []
}

Returns a UserProfile Object

Get user metadata information

Definition

GET /user/{user_id}/metadata/

Example Request


curl  "https://api.automatic.com/user/{user_id}/metadata/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/profile/",
  "user": "https://api.automatic.com/user/U_de0cf1b496008d9b/"
}

Returns a UserMetadata Object

List my devices

Definition

GET /user/{user_id}/device/

Example Request





curl  "https://api.automatic.com/user/{user_id}/device/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/profile/"
}

Returns an array of DeviceUserRelationship Objects

Query Parameters

ParameterDescription
user_id
Optional, default is null
Not provided
device__serial_number
Optional, default is null
(STRING) Serial Number
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

Get a single device's information

Definition

GET /user/{user_id}/device/{device_id}/

Example Request



curl  "https://api.automatic.com/user/{user_id}/device/{device_id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "id": "4aa9b556d5072af84efcb103",
  "url": "https://api.automatic.com/user/U_de0cf1b496008d9b/device/4aa9b556d5072af84efcb103/",
  "version": 2,
  "direct_access_token": "authticket 1 4aa9b556:d5072af8:4efcb103 1 e6d9347e5341ac0a326a 192:8ac04c19:2cab9102:20ce85ef:b7c50475:a1efe6e3:6beb4fc2 1604786476 899dd3350aa9453b709b0d9c21ea4db2e00c1ff604e4a3f24d3c9b65a5dc9543a1ec49f78445f7b27ce291b1aefc75ce221e94cf1b821b2c31157e0b9ef31a7b6b5ca102792392be124278eaa0d3f022f185153b65d548dc7619261a13f20c96dc7c9c5faa8097e3e8c4171f3bed116329a3447eba93ec588884410b92e08068",
  "app_encryption_key": "4b5199c1899da2aa98baeac4af3e078e"
}

Returns a DeviceUserRelationship Object

Vehicle

Vehicle is a core concept in Automatic.

A vehicle may have multiple drivers and a driver may have multiple vehicles.

In actuality, the pairing of a user is to the combination of an Automatic adapter and a vehicle, not directly to the vehicle itself. What this means is that if trips are collected at different times by two different devices in the same vehicle a user would need to be registered to both devices for their token to give access to both sets of trips.

Get a specific vehicle

Definition

GET /vehicle/{id}/

Example Request


curl  "https://api.automatic.com/vehicle/{id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "url": "https://api.automatic.com/vehicle/C_9aa0f0e09383666c/",
  "id": "C_9aa0f0e09383666c",
  "vin": "jtmzf33v895004330",
  "created_at": "2015-07-30T17:33:32.588000Z",
  "updated_at": "2015-07-30T17:33:32.588000Z",
  "make": "Toyota",
  "model": "RAV4",
  "year": 2009,
  "submodel": "Base",
  "display_name": "My Toyota",
  "fuel_grade": "regular",
  "fuel_level_percent": 60.54,
  "battery_voltage": 12.4,
  "active_dtcs": [
    {
      "code": "B0078",
      "created_at": "2015-09-29T23:55:46.123Z",
      "description": "Third Row Right Seatbelt Pretensioner Deployment Control"
    }
  ]
}

Returns a Vehicle Object

Provides a single vehicle's details.

NOTE: VIN number is not necessarily available for all vehicles.

NOTE: color is not yet fully implemented at the time of this writing and will return null until it is.

Get a list of my vehicles

Definition

GET /vehicle/

Example Request








curl  "https://api.automatic.com/vehicle/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "_metadata": {
    "count": 1,
    "next": null,
    "previous": null
  },
  "results": [
    {
      "url": "https://api.automatic.com/vehicle/C_9aa0f0e09383666c/",
      "id": "C_9aa0f0e09383666c",
      "vin": "jtmzf33v895004330",
      "created_at": "2015-07-30T17:33:32.588000Z",
      "updated_at": "2015-07-30T17:33:32.588000Z",
      "make": "Toyota",
      "model": "RAV4",
      "year": 2009,
      "submodel": "Base",
      "display_name": "My Toyota",
      "fuel_grade": "regular",
      "fuel_level_percent": 60.54,
      "battery_voltage": 12.4,
      "active_dtcs": [
        {
          "code": "B0078",
          "created_at": "2015-09-29T23:55:46.123Z",
          "description": "Third Row Right Seatbelt Pretensioner Deployment Control"
        }
      ]
    }
  ]
}

Returns an array of Vehicle Objects

Provides a listing of vehicles that match the query parameters.

Query Parameters

ParameterDescription
created_at__lte
Optional, default is null
(INTEGER) Start time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8"="1431126000
created_at__gte
Optional, default is null
(INTEGER) Start time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
updated_at__lte
Optional, default is null
(INTEGER) End time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8"="1431126000
updated_at__gte
Optional, default is null
(INTEGER) End time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
vin
Optional, default is null
(STRING) VIN Filter
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

List a particular vehicle's MIL history events

Definition

GET /vehicle/{vehicle_id}/mil/

Example Request




curl  "https://api.automatic.com/vehicle/{vehicle_id}/mil/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Example Response

{
  "_metadata": {
    "count": 2,
    "next": null,
    "previous": null
  },
  "results": [
    {
      "code": "B0078",
      "on": true,
      "created_at": "2015-09-30T08:10:31Z",
      "description": "Third Row Right Seatbelt Pretensioner Deployment Control"
    },
    {
      "code": "B0079",
      "on": false,
      "created_at": "2015-08-30T08:06:43Z",
      "description": "Driver Seatbelt Pretensioner \"B\" Deployment Control"
    }
  ]
}

Returns an array of VehicleMILHistory Objects

Query Parameters

ParameterDescription
vehicle_id
Optional, default is null
Not provided
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

API Objects

Below are the serialized definitions of each object type, including the scopes required to retrieve them.

DeviceUserRelationship Object

NameTypeDescriptionScopes
idstringDevice Identifierscope:public
urlstringUser Device Relationship URIscope:public
versionintegerDevice Versionscope:public
direct_access_tokenstringAuthorization token to allow apps to talk to the Adapter directlyscope:adapter:basic scope:public
app_encryption_keystringApplication encryption keyscope:adapter:basic scope:public

Tag Object

NameTypeDescriptionScopes
tagslugscope:public

Trip Object

NameTypeDescriptionScopes
urlstringTrip URIscope:trip
idstringscope:trip
driverstringDriver URIscope:trip
userstringUser URIscope:trip
started_atdatetimeTime at start of tripscope:trip
ended_atdatetimeTime at end of tripscope:trip
distance_mdecimalDistance of trip in metersscope:trip
duration_sstringDuration of trip in secondsscope:trip
vehiclestringVehicle URIscope:trip
start_locationstringLat/Long at start of tripscope:location scope:trip
start_addressModelAddress at start of tripscope:location scope:trip
end_locationstringLat/Long at end of tripscope:location scope:trip
end_addressModelAddress at end of tripscope:location scope:trip
pathstringEncoded path of tripscope:location scope:trip
fuel_cost_usddecimalFuel cost in dollarsscope:behavior scope:trip
fuel_volume_lfloatAmount of fuel used in litersscope:behavior scope:trip
average_kmplfloatFuel efficiency in km/literscope:behavior scope:trip
average_from_epa_kmplfloatFuel efficiency in km/l per the EPAscope:behavior scope:trip
score_eventsdecimalDriving score for eventsscope:behavior scope:trip
score_speedingdecimalDriving score for speedingscope:behavior scope:trip
hard_brakesintegerNumber of hard brakesscope:behavior scope:trip
hard_accelsintegerNumber of hard accelsscope:behavior scope:trip
duration_over_70_sintegerDuration of trip spent over 70 mphscope:behavior scope:trip
duration_over_75_sintegerDuration of trip spent over 75 mphscope:behavior scope:trip
duration_over_80_sintegerDuration of trip spent over 80 mphscope:behavior scope:trip
vehicle_eventsstringVehicle eventsscope:trip scope:vehicle:events
start_timezonestringTimezone at start of tripscope:trip
end_timezonestringTimezone at end of tripscope:trip
city_fractiondecimalFraction of time spent in cityscope:behavior scope:trip
highway_fractiondecimalFraction of time spent on highwayscope:behavior scope:trip
night_driving_fractiondecimalFraction of distance spent driving at nightscope:behavior scope:trip
idling_time_sintegerTime when engine was idlingscope:trip
tagsstringTrip's tagsscope:trip

TripSummaryAddress Object

NameTypeDescriptionScopes
namestringLocation namescope:trip
display_namestringPretty display of addressscope:trip
street_numberstringStreet numberscope:trip
street_namestringStreet namescope:trip
citystringCityscope:trip
statestringStatescope:trip
countrystringCountryscope:trip

TripTagCreate Object

NameTypeDescriptionScopes
tagstringscope:trip
created_atdatetimescope:trip

TripTag Object

NameTypeDescriptionScopes
tagstringTagscope:trip
created_atdatetimeDate when trip was taggedscope:trip

UserMetadata Object

NameTypeDescriptionScopes
urlstringUser Metadata URIscope:user:profile
userstringUser URIscope:user:profile
firmware_versionstringFirmware Versionscope:user:profile
app_versionstringAutomatic App Versionscope:user:profile
os_versionstringOS Versionscope:user:profile
device_typestringType of Devicescope:user:profile
phone_platformstringPhone platformscope:user:profile
is_latest_app_versionbooleanLatest app version installedscope:user:profile
authenticated_clientsstringList of clients that this user has authorized through OAuthscope:user:profile
is_staffbooleanTrue if the user an Automatic staff userscope:user:profile

UserProfile Object

NameTypeDescriptionScopes
urlstringUser Profile URIscope:user:profile
userstringUser URIscope:user:profile
date_joineddatetimeDate user joinedscope:user:profile
tagged_locationsarrayTagged location (i.e., home/work)scope:user:profile

User Object

NameTypeDescriptionScopes
idstringscope:public
urlstringUser URIscope:public
usernamestringUsernamescope:public scope:user:profile
first_namestringFirst namescope:public scope:user:profile
last_namestringLast namescope:public scope:user:profile
emailstringEmail addressscope:public scope:user:profile

VehicleMILHistory Object

NameTypeDescriptionScopes
codestringMalfunction indicator lamp codescope:vehicle:profile
onbooleanIndicates if the light is onscope:vehicle:profile
created_atdatetimeEvent timescope:vehicle:profile
descriptionstringHuman readable description of the MILscope:vehicle:profile

Vehicle Object

NameTypeDescriptionScopes
urlstringVehicle URIscope:public
idstringscope:public
vinstringVehicle Identification Numberscope:public scope:vehicle:vin
created_atdatetimescope:public scope:vehicle:profile
updated_atdatetimescope:public scope:vehicle:profile
makestringMake (Honda, Chevy, etc.,)scope:public scope:vehicle:profile
modelstringModel (Civic, F150, etc.,)scope:public scope:vehicle:profile
yearintegerYearscope:public scope:vehicle:profile
submodelstringSubmodel (EX, Deluxe, etc.,)scope:public scope:vehicle:profile
display_namestringDisplay namescope:public scope:vehicle:profile
fuel_gradechoicescope:public scope:vehicle:profile
fuel_level_percentdecimalAmount of fuel as percentage of total capacityscope:public scope:vehicle:profile
battery_voltagedecimalBattery voltagescope:patron scope:public scope:vehicle:profile
active_dtcsstringCurrently active MILsscope:public scope:vehicle:profile

Errors

The Automatic REST API uses the following HTTP Error codes:

StatusError MessageMeaning
400err_bad_requestRequest is malformed.
401err_unauthorizedNo token or an invalid token is attached to the request.
403err_forbiddenThe token attached to the request doesn't have the scope needed to access this endpoint.
404err_page_not_foundThe specified endpoint cannot be found.
409err_conflictConflict found.
422err_unprocessable_dataThere is an issue processing the body of the request.
500err_internal_errorWe have a problem with our server. Please try again later.
Connection refusedMost likely cause is not using HTTPS.

Streaming API

The Streaming API lets you build a mobile app that speaks directly with our adapter hardware over bluetooth. It is ideal for apps requiring a constant, high-frequency stream of engine data, such as racing or engine diagnostics.

The Automatic Streaming SDK supports the streaming of a subset of ELM327 commands over a standard BluetoothSocket.

Command Pipelining

The Automatic Adapter’s ELM 327 interface breaks its input stream into lines and responds to each line in order. If echo is on, it echoes one line at a time, responding to each line before echoing the next line. Your app can pipeline multiple commands and receive the responses independently. Doing so yields much higher throughput than sending one command at a time and waiting for a response before sending another command.

As an extension, the adapter supports the CAN multipid request syntax (e.g., 01040C0D0F101F) with all protocols, not just CAN. However, the response is always returned in CAN format, regardless of the actual OBD bus protocol that ATDPN returns. The fastest throughput for mode 01 PID requests is achieved by requesting six PIDs at a time (the maximum) using the multipid syntax, pipelining those requests, and using the following response format settings:

SettingMeaning
ATE0echo off
ATS0no spaces
ATCAF1CAN auto-formatting, the default
ATH0no headers, the default
ATL0no linefeeds, the default

If you do not see a command you need listed below, please contact us and we would be happy to consider adding it.

Available PIDs

The Automatic Adapter exposes ECM data for all mode 01 PIDs that are defined in SAE J1979-DA. Also, all mode 09 ECM PIDs on non-J1850 vehicles. Data from other ECUs is currently not available.

PID Caching and Refreshing

The first time your app requests a mode 01 PID—or if it hasn’t requested it for some time—the adapter schedules that PID to get refreshed periodically. The value is cached each time it is refreshed, and your app sees the most recently cached value. The adapter will try to refresh PIDs at the rates listed below on CAN vehicles, and no faster than 1 Hz on non-CAN vehicles. PIDs that aren’t refreshed are cached until the next ignition-on. The adapter stops refreshing any PID that your app hasn’t requested in awhile. Mode 09 PIDs are not cached, and the adapter will request them from the vehicle on demand.

The following refresh rates are subject to change:

PIDRefresh Rate
00 - Supported PIDs 01-20-
01 - Monitor status since DTCs cleared-
02 - DTC that caused required freeze frame data storage-
03 - Fuel system status0.1 Hz
04 - Calculated LOAD Value1 Hz
05 - Engine Coolant Temperature1 Hz
06 - Short Term Fuel Trim - Bank 1/Bank 35 Hz
07 - Long Term Fuel Trim Bank 1/Bank 35 Hz
08 - Short Term Fuel Trim - Bank 2/Bank 45 Hz
09 - Long Term Fuel Trim - Bank 2/Bank 45 Hz
0A - Fuel Pressure (gauge)1 Hz
0B - Intake Manifold Absolute Pressure0.5 Hz
0C - Engine RPM5 Hz
0D - Vehicle Speed Sensor1 Hz
0E - Ignition Timing Advance for #1 Cylinder5 Hz
0F - Intake Air Temperature1 Hz
10 - Air Flow Rate from Mass Air Flow Sensor5 Hz
11 - Absolute Throttle Position5 Hz
12 - Commanded Secondary Air Status-
13 - Location of Oxygen Sensors-
14 - O2 Sensor Voltage / Short Term Fuel Trim - 1.15 Hz
15 - O2 Sensor Voltage / Short Term Fuel Trim - 1.25 Hz
16 - O2 Sensor Voltage / Short Term Fuel Trim - 1.3 or 2.15 Hz
17 - O2 Sensor Voltage / Short Term Fuel Trim - 1.4 or 2.25 Hz
18 - O2 Sensor Voltage / Short Term Fuel Trim - 2.1 or 3.15 Hz
19 - O2 Sensor Voltage / Short Term Fuel Trim - 2.2 or 3.25 Hz
1A - O2 Sensor Voltage / Short Term Fuel Trim - 2.3 or 4.15 Hz
1B - O2 Sensor Voltage / Short Term Fuel Trim - 2.4 or 4.25 Hz
1C - OBD requirements to which vehicle or engine is certified.-
1D - Location of oxygen sensors-
1E - Auxiliary Input Status-
1F - Time Since Engine Start1 Hz
20 - Supported PIDs 21-40-
21 - Distance Traveled While MIL is Activated1 Hz
22 - Fuel Pressure relative to manifold vacuum1 Hz
23 - Fuel Rail Pressure1 Hz
24 - O2 Lambda / Sensor Voltage - 1.15 Hz
25 - O2 Lambda / Sensor Voltage - 1.25 Hz
26 - O2 Lambda / Sensor Voltage - 1.3 or 2.15 Hz
27 - O2 Lambda / Sensor Voltage - 1.4 or 2.25 Hz
28 - O2 Lambda / Sensor Voltage - 2.1 or 3.15 Hz
29 - O2 Lambda / Sensor Voltage - 2.2 or 3.25 Hz
2A - O2 Lambda / Sensor Voltage - 2.3 or 4.15 Hz
2B - O2 Lambda / Sensor Voltage - 2.4 or 4.25 Hz
2C - Commanded EGR1 Hz
2D - EGR Error0.1 Hz
2E - Commanded Evaporative Purge0.1 Hz
2F - Fuel Level Input1/60 Hz
30 - Number of warm-ups since DTCs cleared-
31 - Distance traveled since DTCs cleared0.1 Hz
32 - Evap System Vapor Pressure0.1 Hz
33 - Barometric Pressure0.1 Hz
34 - O2 Lambda / Sensor Current - 1.15 Hz
35 - O2 Lambda / Sensor Current - 1.25 Hz
36 - O2 Lambda / Sensor Current - 1.3 or 2.15 Hz
37 - O2 Lambda / Sensor Current - 1.4 or 2.25 Hz
38 - O2 Lambda / Sensor Current - 2.1 or 3.15 Hz
39 - O2 Lambda / Sensor Current - 2.2 or 3.25 Hz
3A - O2 Lambda / Sensor Current - 2.3 or 4.15 Hz
3B - O2 Lambda / Sensor Current - 2.4 or 4.25 Hz
3C - Catalyst Temperature Bank 1, Sensor 11 Hz
3D - Catalyst Temperature Bank 2, Sensor 11 Hz
3E - Catalyst Temperature Bank 1, Sensor 21 Hz
3F - Catalyst Temperature Bank 2, Sensor 21 Hz
40 - Supported PIDs 41-60-
41 - Monitor status this driving cycle1/60 Hz
42 - Control module voltage0.1 Hz
43 - Absolute Load Value1 Hz
44 - Fuel/Air Commanded Equivalence Ratio1 Hz
45 - Relative Throttle Position5 Hz
46 - Ambient air temperature0.1 Hz
47 - Absolute Throttle Position B5 Hz
48 - Absolute Throttle Position C5 Hz
49 - Accelerator Pedal Position D5 Hz
4A - Accelerator Pedal Position E5 Hz
4B - Accelerator Pedal Position F5 Hz
4C - Commanded Throttle Actuator Control5 Hz
4D - Engine run time while MIL is activated0.1 Hz
4E - Engine run time since DTCs cleared0.1 Hz
4F - External Test Equipment Configuration Information #11/60 Hz
50 - External Test Equipment Configuration Information #21/60 Hz
51 - Type of fuel currently being utilized by the internal combustion engine-
52 - Alcohol Fuel Percentage1/60 Hz
53 - Absolute Evap System Vapor Pressure-
54 - Evap System Vapor Pressure-
55 - Short Term Secondary O2 Sensor Fuel Trim Banks 1 & 35 Hz
56 - Long Term Secondary O2 Sensor Fuel Trim Banks 1 & 35 Hz
57 - Short Term Secondary O2 Sensor Fuel Trim Banks 2 & 45 Hz
58 - Long Term Secondary O2 Sensor Fuel Trim Banks 2 & 45 Hz
59 - Fuel Rail Pressure1 Hz
5A - Relative Accelerator Pedal Position5 Hz
5B - Hybrid/EV Battery Pack Remaining Charge0.1 Hz
5C - Engine Oil Temperature0.1 Hz
5D - Fuel Injection Timing0.1 Hz
5E - Engine Fuel Rate0.1 Hz
5F - Emission requirements to which vehicle is designed-
60 - Supported PIDs 61-80-
61 - Driver's Demand Engine - Percent Torque1 Hz
62 - Actual Engine - Percent Torque1 Hz
63 - Engine Reference Torque1 Hz
64 - Engine Percent Torque Data1 Hz
65 - Auxiliary Inputs / Outputs1 Hz
66 - Mass Air Flow Sensor5 Hz
67 - Engine Coolant Temperature0.1 Hz
68 - Intake Air Temperature Sensor0.1 Hz
69 - Commanded EGR and EGR Error0.1 Hz
6A - Commanded Diesel Intake Air Flow Control and Relative Intake Air Flow Position1 Hz
6B - Exhaust Gas Recirculation Temperature1 Hz
6C - Commanded Throttle Actuator Control and Relative Throttle Position5 Hz
6D - Fuel Pressure Control System1 Hz
6E - Injection Pressure Control System1 Hz
6F - Turbocharger Compressor Inlet Pressure1 Hz
70 - Boost Pressure Control1 Hz
71 - Variable Geometry Turbo (VGT) Control1 Hz
72 - Wastegate Control1 Hz
73 - Exhaust Pressure1 Hz
74 - Turbocharger RPM5 Hz
75 - Turbocharger A Temperature0.1 Hz
76 - Turbocharger B Temperature0.1 Hz
77 - Charge Air Cooler Temperature (CACT)0.1 Hz
78 - Exhaust Gas Temperature (EGT) Bank 10.1 Hz
79 - Exhaust Gas Temperature (EGT) Bank 20.1 Hz
7A - Diesel Particulate Filter (DPF) Bank 10.1 Hz
7B - Diesel Particulate Filter (DPF) Bank 20.1 Hz
7C - Diesel Particulate Filter (DPF) Temperature0.1 Hz
7D - NOx NTE control area status0.1 Hz
7E - PM NTE control area status0.1 Hz
7F - Engine Run Time1 Hz
80 - Supported PIDs 81-A0-
81 - Engine Run Time for AECD #1 - #51 Hz
82 - Engine Run Time for AECD #6 - #101 Hz
83 - NOx Sensor1 Hz
84 - Manifold Surface Temperature0.1 Hz
85 - NOx Control System1 Hz
86 - Particulate Matter (PM) Sensor1 Hz
87 - Intake Manifold Absolute Pressure0.5 Hz
88 - SCR inducement system actual state0.1 Hz
89 - Engine Run Time for AECD #11 - #151 Hz
8A - Engine Run Time for AECD #16 - #201 Hz
8B - Diesel Aftertreatment Status-
8C - O2 Sensor (Wide Range)5 Hz
8D - Absolute Throttle Position G5 Hz
8E - Engine Friction - Percent Torque1 Hz
8F - Particulate Matter (PM) Sensor Output1 Hz
90 - WWH-OBD Vehicle OBD System Information-
91 - WWH-OBD ECU OBD System Information-
92 - Fuel System Control Status (Compression Ignition)0.1 Hz
93 - WWH-OBD Vehicle OBD Counters-
94 - NOx control - driver inducement system status and counters-
98 - Exhaust Gas Temperature (EGT) Bank 10.1 Hz
99 - Exhaust Gas Temperature (EGT) Bank 20.1 Hz
9A - Hybrid/EV Vehicle System Data-
9B - Diesel Exhaust Fluid Sensor Output0.1 Hz
9C - O2 Sensor (Wide Range)5 Hz
9D - Engine Fuel Rate1 Hz
9E - Engine Exhaust Flow Rate1 Hz
9F - Fuel System Percentage Use0.1 Hz
A0 - Supported PIDs A1-C0-
A1 - NOx Sensor Corrected0.1 Hz
A2 - Cylinder Fuel Rate0.1 Hz