Note: This documentation is for a deprecated version of Automatic’s API. View the current API reference.

Introduction

We provide two APIs for interacting with Automatic data. Both are detailed in this document:

  • REST API - lets your application request data from Automatic.
  • Event Webhook API - pushes event data to a listener URL on your application.

The REST API is considered our source of truth. The Event Webhook API is provided as a convenience service, but is not guaranteed to the same standard as our REST API on data completeness.

Both APIs deliver data as JSON.

Status

The API is in beta. Whenever possible, we’ll give developers 45 days notice of any breaking changes to the API.

Privacy

HTTPS is required for all Automatic Event Webhook APIs because private user information will be transmitted. Users trust your application with this info 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. Need to host an app with https, but don’t want to have the hassle of obtaining your own SSL certificate? Heroku provides free piggyback SSL certificates on *.herokuapp.com sites by default.

Authentication

OAuth2 is required to authenticate.

1. Redirect users to request Automatic access

GET https://accounts.automatic.com/oauth/authorize
Parameters
NameDescription
client_idRequired stringThe client ID for your application
scopeRequired stringSpace separated list of scopes that your application needs
response_typeRequired stringValue should be "code"
stateOptional stringAn unguessable random string. It is used to protect against cross-site request forgery attacks.

As an example, the authorize URL formatted for the 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

For convenience, a formatted authorize URL including your client_id is provided for each application in the Developer Apps Manager.

2. Automatic redirects back to your site

If the user accepts your request, Automatic redirects back to your site with a temporary code in a code GET parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

Exchange this for an access token:

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"
Response

The response will be in JSON format:

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

Enter client_secret, client_id and code (from step 1 above) for this curl statement to work.

curl --data "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_CODE_FROM_STEP_1&grant_type=authorization_code" https://accounts.automatic.com/oauth/access_token

3. Use the access token to access the API

The access token allows you to make requests to the API on a behalf of a user.

$ curl -H "Authorization: token YOUR-OAUTH-TOKEN" "https://api.automatic.com/v1/trips"

4. Refresh Tokens

Once the access token eventually expires, you can exchange the refresh token for a new access token

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
refresh_tokenRequired stringThe refresh token obtained with the (now expired) access token
grant_typeRequired stringValue MUST be set to "refresh_token"
Response

The response is the same format as the /oauth/access_token endpoint.

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

Scopes

Scopes let you specify exactly what type of access your application needs. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

Requested scopes will be displayed to the user on the authorize form.

Scope NameDescription
scope:publicAccess to public information about user.
scope:user:profileAccess to user’s profile (i.e. first_name, last_name).
scope:locationAccess to location. Applies to all events.
scope:current_locationAccess to user’s current location.
scope:vehicle:profileAccess to vehicle information (i.e. year, make, model). Applies to all events.
scope:vehicle:eventsAccess to real-time vehicle events (i.e. hard_brake, hard_accel).
scope:vehicle:vinAccess to vehicle VIN.
scope:tripAccess to user’s trips.
scope:behaviorAccess to user’s driving profile.
scope:adapter:basicDirect bluetooth access to all Adapters on user’s account.

Webhook API

The Event Webhook API lets you register a URL to which we will send an HTTP POST request anytime an event happens for a user and scope for which your application is authorized. Your server will receive a POST request where the body is a JSON object. Each JSON object will contain a type parameter which will match one of the event types listed below.

Responding to a Webhook

Your application should respond with a 200 HTTP status code to acknowledge successful receipt of a webhook. Any non 200-range response will indicate that you did not receive the webhook. As of now, requests will not be retried.

Common Uses for Automatic Webhooks

  • Notifying someone based on an event, such as "ignition" on.
  • Getting data about MIL (check engine) light status.
  • Trigger some action based on a user’s location.

Testing Webhooks

You can test the webhooks by logging into the Developer Apps Manager and using the "Test Webhook" section under "Testing Tools".

Types of Webhooks

Event NameDescription
trip:finishedSent after a trip is completed and processed by Automatic.
ignition:onSent when vehicle ignition is turned on.
ignition:offSent when vehicle ignition is turned off. Note that this happend before trip:finshed.
notification:speedingSent after a "velocity exceeded threshold" event occurs.
notification:hard_brakeSent when a hard baking event occurs.
notification:hard_accelSent when a hard acceleration event occurs.
mil:onSent when an MIL (check engine light) comes on.
mil:offSent when an MIL (check engine ligh) goes off.

Identifying Users

Each webhook contains a user object that contains an id and v2_id. If you are using version 1 of the Automatic API (detailed below on this page), refer to the id field. Version 2 of our REST API is under development and will be using a different user id scheme. In attempt to make that change non breaking, we’re preemptively adding the v2_id field. Version 2 user IDs will begin with U_.

While v2 is still in pre-release, you can contact developer@automatic.com if you’d like to learn more or get alpha access.

Sample Event Objects

Note that in order to get vehicle and location objects, an app must request the appropriate scope.

trip:finished

Requires scope:trip scope. See trip object. See vehicle object.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "trip:finished",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "trip" {
    // Trip Object
  }
}

ignition:on

Requires scope:vehicle:events scope. See vehicle object.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "ignition:on",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  }
}

ignition:off

Requires scope:vehicle:events scope. See vehicle object.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "ignition:off",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  }
}

notification:speeding

Requires scope:vehicle:events scope. See vehicle object.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "notification:speeding",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "speed_mph": 70
}

notification:hard_brake

Requires scope:vehicle:events scope.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "notification:hard_brake",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "g_force": 0.3
}

notification:hard_accel

Requires scope:vehicle:events scope. See vehicle object.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "notification:hard_accel",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "g_force": 0.3
}

mil:on

Requires scope:vehicle:events scope. See vehicle object.

Note that dtcs is an array and can include more than one trouble code, if more than one contributed to the MIL event.

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.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "mil:on",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "start": 1383448450301
    }
  ]
}

mil:off

Requires scope:vehicle:events scope. See vehicle object.

Note that dtcs is an array and can include more than one trouble code, if more than one contributed to the MIL event.

{
  "id": "E_63db5c25ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615",
    "v2_id": "U_9855dcf2030c0111"
  },
  "type": "mil:off",
  "created_at": 1383448450201,
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10
  },
  "vehicle": {
    // Vehicle Object
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "start": 1383448450301
    }
  ],
  "user_cleared": true
}

REST API

The REST API allows your application to request data. The base URL end point at this time is - https://api.automatic.com/v1/

Authentication

A valid OAuth token must be present in the Authorization header of each request.

$ curl -H "Authorization: token YOUR-OAUTH-TOKEN" "PATH-TO-RESOURCE"
Example
$ curl -H "Authorization: token PrBfQ1sp534wDaaU7tbBTVObqj83QUekVemnEsXs" "https://api.automatic.com/v1/trips"

Trips

List trips for authenticated user

GET /trips
Scopes

Requires the scope:trip scope.

Parameters
NameDescription
startOptional integerUnix timestamp in milliseconds to query for trips newer than. Uses trip start_time. For example: 1401666528657.
endOptional integerUnix timestamp in milliseconds to query for trips older than. Uses trip start_time. For example: 1405907957600.
pageOptional integerPage number to retrieve. Default is page 1.
per_pageOptional integerNumber of trips per page to return. Default is 100.
Response

The response will be an array of trip objects. If a start or end parameter are included with the request, these will be honored. Otherwise, the most recent trip will be returned first.

[
  {
    "uri": "https://api.automatic.com/v1/trips/524da549e4b08d1af17f6dca",
    "id": "T_8e7b567626c26695",
    "user": {
      "id": "2fcd8161801e95d1e615"
    },
    "vehicle": {
      // Vehicle Object
    },
    "start_location": {
      "name": "Ashbury St, SF, CA",
      "display_name": "Home",
      "lat": 37.7692903,
      "lon": -122.4465469,
      "accuracy_m": 5
    },
    "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": 97.88124084472656
    },
    "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,
    "drive_events": [
      {
        "type": "speeding",
        "start_distance_m": 4193.749999999999,
        "end_distance_m": 4383.416666666666,
        "start_time": 1383448690201,
        "end_time": 1383448692301,
        "velocity_mph": 70
      },
      {
        "type": "hard_accel",
        "lat": 38.4184716230387,
        "lon": -122.71354039973721,
        "ts": 1383449948101,
        "g": 0.351
      },
      {
        "type": "hard_brake",
        "lat": 37.82475806798236,
        "lon": -122.31403562609702,
        "ts": 1383449946901,
        "g": 0.611
      }
    ]
  }
]
Pagination

100 results will be returned by default. An optional ?page parameter can be added to specify which page to return. To control the size of the page, the ?per_page parameter can be added.

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Example
GET /trips?page=2&per_page=30
Link Header

Pagination info is included in a Link Header. The link header includes links, where relevant to the next, previous, first and last pages.

Link: <https://api.automatic.com/v1/trips?page=3&per_page=100>; rel="next",
<https://api.automatic.com/v1/trips?page=27&per_page=100>; rel="last"

The type of link is shown as the rel attribute.

Get a single trip

GET /trips/:id
Scopes

Requires the scope:trip scope.

Parameters
NameDescription
idRequired stringID of a the trip you’d like to retrieve
Response

The response will be a single trip object.

User

Get info about the authenticated user

GET /user
Scopes

No specific scope required

Response
{
  "id": "2fcd8161801e95d1e615",
  "first_name": "Mary",
  "last_name": "Driverton",
  "email": "developer@automatic.com"
}
NameDescription
idThe user ID of the authenticated user.
first_nameThe first name of the authenticated user. Requires scope:user:profile scope.
last_nameThe last name of the authenticated user. Requires scope:user:profile scope.
emailThe email of the authenticated user. Requires scope:user:profile scope.

Vehicles

List vehicles for authenticated user

GET /vehicles
Scopes

If the app had the scope:vehicle:profile scope, then information about each vehicle will be returned. If the app does not have this scope, only the id field will be returned.

Response

The response will be an array of vehicle objects.

[
  {
    "uri": "https://api.automatic.com/v1/vehicles/524da549e4b08d1af17f6dca",
    "id": "C_8e7b567626c26695",
    "year": "2001",
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  }
]

Get a single vehicle

GET /vehicles/:id
Scopes

Requires the scope:vehicle:profile scope.

Parameters
NameDescription
idRequired stringID of a the vehicle you’d like to retrieve
Response

The response will be a single vehicle object.

Errors

Errors are sent as JSON with a message attribute with an approproate HTTP status code.

Example Error response

{
  "message": "Invalid OAuth Token"
}

Error List

Below is a full list of errors that the Automatic REST API may respond with.

Status CodeMessageDescription
403Invalid ScopeThe token attached to the request did not have the scope needed to access this endpoint. See the list of scopes.
403Invalid OAuth TokenThe token attached to the request was invalid. This may mean the token has expired.
404Not FoundThe resource requested doesn’t exist, or the token attached to the request doesn’t have access.
404Use https://api.automatic.comAll API requests must use https. Make sure you are requesting https://api.automatic.com.
500Server ErrorSomething is wrong on our servers. Try again, or let us know about the issue.

Automatic Data

The Trip Object

NameDescription
uriAPI URI to the trip object.
idA unique identifier for the trip.
userAn object containing id which is a unique identifier for the user.
vehicleA vehicle object
start_locationThe start location of the trip as a location object with name, display_name, lat, lon and accuracy_m. Requires scope:location scope.
start_timeThe start time of the trip started in as unix timestamp in milliseconds.
start_time_zoneThe start timezone of the trip.
end_locationThe end location of the trip as a location object with name, display_name, lat, lon and accuracy_m. Requires scope:location scope.
end_timeThe end time of the trip started as unix timestamp in milliseconds.
end_time_zoneThe end timezone of the trip
pathThe trip path as an encoded polyline. Requires scope:location scope
distance_mThe trip distance in meters.
hard_accelsThe number of hard acceleration events during the trip. Requires scope:trip:events scope.
hard_brakesThe number of hard braking events during the trip. Requires scope:trip:events scope.
duration_over_80_sThe number of seconds over 80 mph during the trip. Requires scope:trip:events scope.
duration_over_75_sThe number of seconds over 75 mph during the trip. Requires scope:trip:events scope.
duration_over_70_sThe number of seconds over 70 mph during the trip. Requires scope:trip:events scope.
fuel_cost_usdThe fuel cost in USD for the trip.
fuel_volume_galThe volume of fuel used for the trip in gallons.
average_mpgThe average miles per gallon for the trip.
drive_eventsAn array of drive events (hard brakes, hard accels and speeding) during the trip. Requires scope:vehicle:events scopes.

Example Trip Object

{
  "uri": "https://api.automatic.com/v1/trips/524da549e4b08d1af17f6dca",
  "id": "T_db5c2635ffd955ba",
  "user": {
    "id": "2fcd8161801e95d1e615"
  },
  "vehicle": {
    "uri": "https://api.automatic.com/v1/vehicles/529e5772e4b00a2ddb562f1f",
    "id": "C_8e7b567626c26695",
    "year": 2001,
    "make": "Acura",
    "model": "MDX",
    "color": "#d15fed",
    "display_name": "My Speed Demon"
  },
  "start_location": {
    "name": "Ashbury St, SF, CA",
    "display_name": "Home",
    "lat": 37.7692903,
    "lon": -122.4465469,
    "accuracy_m": 5
  },
  "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": 97.88124084472656
  },
  "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,
  "drive_events": [
    {
      "type": "speeding",
      "start_distance_m": 4193.749999999999,
      "end_distance_m": 4383.416666666666,
      "start_time": 1383448690201,
      "end_time": 1383448692301,
      "velocity_mph": 70
    },
    {
      "type": "hard_accel",
      "lat": 38.4184716230387,
      "lon": -122.71354039973721,
      "ts": 1383449948101,
      "g": 0.351
    },
    {
      "type": "hard_brake",
      "lat": 37.82475806798236,
      "lon": -122.31403562609702,
      "ts": 1383449946901,
      "g": 0.611
    }
  ]
}

The Vehicle Object

NameDescription
uriAPI URI to the vehicle object.
idA globally unique identifier for the vehicle.
yearYear of the vehicle.
makeMake of the vehicle.
modelModel of the vehicle.
colorThe vehicle color, set by the user in hexidecimal RGB.
display_nameA nicely formatted name of the vehicle. If a custom name has been set by the user, it is used. Otherwise a string with vehicle make and model is provided (i.e. "Acura MDX"). Use this in the UI to identify vehicles.

Note that all fields expect uri and id require the scope:vehicle:profile scope.

Example Vehicle Object

{
  "uri": "https://api.automatic.com/v1/vehicles/529e5772e4b00a2ddb562f1f",
  "id": "C_8e7b567626c26695",
  "year": 2001,
  "make": "Acura",
  "model": "MDX",
  "color": "#d15fed",
  "display_name": "My Speed Demon"
}