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:

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

####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

####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

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.

• Javascript
• Java
• Python
• Go
• Swift
• C++

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.

GET /device/

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

{
  "_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"
    }
  ]
}

GET /device/{device_id}/

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

{
  "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"
}

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/

GET /tag/

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

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

GET /tag/{slug}/

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

{
  "tag": "business"
}

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 /trip/{id}/

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

{
  "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"
  ]
}

GET /trip/

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"

{
  "_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"
      ]
    }
  ]
}

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

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

{}

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

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

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

POST /trip/{trip_id}/tag/

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

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

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/{id}/

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

{
  "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"
}

GET /user/{user_id}/profile/

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

{
  "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": []
}

GET /user/{user_id}/metadata/

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

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

GET /user/{user_id}/device/

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

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

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

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

{
  "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"
}

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 /vehicle/{id}/

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

{
  "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"
    }
  ]
}

GET /vehicle/

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

{
  "_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"
        }
      ]
    }
  ]
}

GET /vehicle/{vehicle_id}/mil/

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

{
  "_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"
    }
  ]
}

API Objects

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

DeviceUserRelationship Object

Tag Object

Trip Object

TripSummaryAddress Object

TripTagCreate Object

TripTag Object

UserMetadata Object

UserProfile Object

User Object

VehicleMILHistory Object

Vehicle Object

Errors

The Automatic REST API uses the following HTTP Error codes:

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:

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: