Welcome
Getting Started
In this page you’ll find the reference materials and tools needed to get started building applications with Automatic’s APIs. At present, there are three different APIs to serve various requirements of your application, each detailed below, which can be used in conjunction with one another. Additionally, there are wrapper libraries, SDKs, and sample code apps to make developing as easy as possible.
You do not need an Automatic device in order to build applications. The first step is to register a platform application by logging in (upper right corner on this page) and then managing your apps. If you don’t have an account with us, you’ll be able to create one there as well.
The APIs have no restrictions in development mode (up to 25 users). There is a quick approval process before changing to production mode since we’d like to ensure apps meet our safety and privacy policies.
Should you run into any technical issues, please contact us using the link at the bottom of this page or by emailing [email protected]. For business development inquiries, please contact [email protected].
REST API
The REST API is our service for requesting or writing data on demand from Automatic’s cloud. It is our source of truth for historical records and ideal for creating applications that need the driving history or profile details of a user or vehicle. All results from the native API are given in JSON. Refer to the Full API Reference for details.
Real-time Event APIs
Automatic provides real time events via websockets or webhooks and Automatic’s Android SDK. You can eliminate the need to continually poll the REST API.
The websocket API provides real-time notifications of user and vehicle events, including current location.
The webhook API provides real-time notifications of user and vehicle events as HTTP POST requests to a URL that you specify. Because it requires a static URL to receive the webhooks, it is not suitable for client-side only mobile apps.
Automatic’s Android SDK provides simple callback access to real-time events such as: Ignition On/Off, MIL On/Off, Hard Events, and Location Change.
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. This API is in a closed beta at the moment. If you would like to create an app with this API, please fill out this form explaining your proposed app.
References
Full API Reference
Please see our full REST and Real-time Event API documentation. This includes a walkthrough of our Authorization scheme, which is OAuth 2.0
Sample Apps
The following sample applications demonstrate common uses of automatic data across various languages. They are intended to be as barebones as possible so that you can isolate and understand the functionality.
OAuth Example App (Node.js)
A node.js app that demonstrates how to authenticate with Automatic using OAuth.
Demo | CodeWebsocket Events Example App (Node.js)
A node.js app that uses websockets to listen to the Automatic Events API.
Demo | CodeWebhook Events Example App (Node.js)
A node.js app that listens to webhooks from the Automatic Events API.
Demo | CodeTripViewer (Node.js)
View and export your Automatic trips. Tripviewer shows past trips and allows data export as CSV or JSON. It demonstrates the use of the Automatic REST API.
Demo | CodeTripViewer (Rails)
A rails implementation of the TripViewer app. Automatic’s “Hello World.”
Demo | CodeDeveloper Token Manager (Rails)
A utility to assist developers in getting their own personal tokens to work with the Automatic API.
CodeOmniauth-automatic Demo (Sinatra)
A demonstration of the omniauth scheme for automatic using Sinatra.
Demo | CodeAutomatic Weekly Stats
App that collects your weekly trip history and provides summary statistics.
Demo | CodeAutomatic SMS with Twilio
This app lets you setup a rule to text a friend or family member when you begin a trip meeting certain conditions. It is a demonstration of the Automatic API mashed up with Twilio.
Demo | CodeWebhook Email Example
This app will let you register yourself then listen for the engine trouble code webhooks (MIL:On). Upon receiving one, it will send an email. This is a useful starting point for any service that would like to react to customers needs with a targeted offering.
CodeLibraries & Utilities
1st Party Libraries & Utilities
iOS
Android
node.js
- passport-automatic: Passport strategy for authenticating with Automatic using the OAuth 2.0 API.
Ruby
- omniauth-automatic: OmniAuth strategy for Automatic.
Resources
Product and Brand Images
Product and brand image assets to use in your marketing materials are available at automatic.com/press.
Developer Marketing Support
We love to work with developers who build apps with our APIs to get the word out and to help get your app in front of lots of users.
The purpose of this section is to:
- Explain how we work with developers to market their apps.
- Provide clear definitions for terms so you can refer to Automatic products and services consistently.
- Share design assets for you to use in your apps
Marketing Your Apps
We want to create the world’s first and best app store for cars. We’re a friendly bunch and love working with developers to promote the great apps built on the Automatic platform. Here are the ways we can market your car apps.
Presence in the App Gallery
Apps that meet our high standards of quality appear in the Automatic App Gallery, a curated selection of apps built on the Automatic platform. Each app gets its own page with a detailed description, screenshots, and links to where the app is hosted. (e.g. App Store, Google Play, or web app URL).
App Gallery Submission Guidelines
Featured Apps
Especially useful and well-made apps may be featured with prominent placement in the Automatic App Gallery, on automatic.com, and in the Automatic mobile apps.
When you’re ready to ship your app
When you’re ready to submit a new app or major app update to the Automatic App Gallery, we want to help you make as big a splash as possible.
We would like to promote each new app in the Automatic App Gallery. Here are the factors we take into consideration when we’re trying to determine the scale and extent of the promotion:
- How cool or unique is the app?
- How high is the production quality?
- How interesting is it to Automatic drivers?
- How effectively does it use the Automatic platform?
- How much confidence you can give us that your users will be well supported?
- How much confidence you can give us that the app will be well maintained and improved?
Terminology
Naming things is hard! We’ve learned (the hard way) that maintaining consistency in what things are called makes for a much better user experience. Here’s how to refer to Automatic products, services, and programs accurately and consistently.
Hardware
The physical product you plug into a car is called the “Automatic connected car adapter.“ When referring to it multiple times on a page, use “Automatic adapter,“ “car adapter,“ or simply “adapter.“
Diagnostic Port
When referring to the port the Automatic adapter plugs into, it is best to call it the “diagnostic port.“ This is the preferred term because it’s not overly technical-sounding. This port is officially known as the ”OBD-II“ port, which stands for on-board diagnostics.
App Gallery
The “Automatic App Gallery” is a section of our website and mobile apps that features many of the car apps created in the Automatic Developer Program.
The Automatic Logo
Whenever you need to represent Automatic visually in your app or marketing materials, use the horizontal Automatic logo.
Preferred (Gray)
The gray logo is preferred, but should only be used on white (or near-white) backgrounds.
Secondary (White)
For dark backgrounds, use the white logo.
Authentication Buttons
Your apps need a way to connect with a driver’s Automatic account and request access to driving data like trips history or ignition events. There are two ways to do this.
Connect with Automatic
When your app needs to request access to a driver’s Automatic account, use the “Connect with Automatic” button to present the authorization web page. This is the correct way for most apps to request access to a driver’s data.
Log In with Automatic
You can use the “Log in with Automatic” button to simultaneously log a user into your app and request access to their driving data. This authentication method is appropriate when your app requires Automatic data to be useful and has no need for its own login credentials.
Connected
Creating Your Own Button
We strongly recommend using the provided buttons in your apps, but if you prefer to create your own to match your app better, please observe these guidelines:
- To avoid user confusion, use the above button copy only. Do not include any other text.
- Use approved Automatic colors.
- Use the provided white Automatic logo mark in the button.
Submit Your App
Would you like to make your application available to a larger audience? Want to be listed in the Automatic App Gallery and other promotional activity?
By default, all new platform apps are initially in a test mode. This limits you to twenty-five access tokens. To move beyond test mode, you will need to submit your app for review. There are three potential levels of review:
Technical Review
We need to make sure that you adhere to the terms of service, are accessing only the data scopes that your app reasonably needs, and that the app functions as intended, providing a good user experience.
NOTE: we do not have separate development and production application keys. Rather, we flip a switch for your application to be put into production mode. So the output of these steps is for us to flip the bit. If you were developing on a different URL than the one you’ll use for production, you’ll need to change the OAuth callback and webhook URLs (if applicable) for your application in the Developer Apps Manager.
If you are building a tool for personal or internal use at a company, this is the only review that will be needed. If you are planning to make your app available to a general audience, would like it to be included in our App Gallery, plan to monetize the data that you get from Automatic, or would like other promotional help from Automatic, some or all of the following reviews are needed as well.
Product & Design Review
We like to ensure that users will have a delightful experience with any apps on the Automatic platform. Our team will review your app and for some schedule a demo time. We will give any applicable feedback about UX patterns and design elements that we’ve found to be more or less successful with our users.
Marketing Review
If you’d like to be listed in the app gallery, our marketing team will get in touch about content and assets needed. They will also make sure that you are following our branding guidelines on usage of the Automatic name, key terminology, logos, product images, and so forth. This is the team with which to discuss lightweight promotional activities like social posts, newsletter and blog inclusion, and discounts for your users.
Business Review
For some apps, we find it helpful to both parties to put a commercial agreement in place. This usually comes up if you would like to offer a paid service using Automatic APIs, have a large user base to aid distribution of Automatic, would like to resell our devices, or other such arrangements where it would be useful to lay out terms of the relationship. If you believe this applies to what you are doing, please get in contact early. [email protected] is the place to start this. Our team will also review apps that are going through the other approval processes and may reach out to you to discuss terms once you’ve submitted your app.
How to Submit
To begin the submission process, please request a review in your Developer Apps Manager once logged in or email [email protected].
ToS Principles
Developers, this is for you. We’re stoked that you’re building an application on the Automatic platform. When you’re ready for us to move your app into Production Mode so you can launch it, we’ll review it to make sure it complies with this policy, so read on! Follow the guidelines below to speed your way to launch.
- Build a quality product.
- Your app must be stable and not crash.
- Your app should not confuse, deceive, defraud, mislead, or spam anyone.
- Your app must do the things that it claims to do, and must not do things that are inconsistent with what it claims to do.
- Your app must be easily navigable.
- Your app must be functional with no obvious bugs.
- Your app’s meta-information—its name, icon, and description—must comply with our brand guidelines.
- Your app must follow any relevant best practices we include in our technical documentation.
- Protect people’s data.
- User data you obtain through our API belongs to your users, not to you.
- Your app must request only the data it needs. This means:
- Your app must not request scopes that the app does not need.
- If your app does not use webhooks, you must disable them in the Developer App Manager.
- Protect the data you receive from us against unauthorized access or use.
- If you cache data you receive from us, keep the cached data up to date.
- Don’t proxy, request or collect Automatic usernames or passwords. Use OAuth to authenticate users.
- Don’t sell, license, or purchase any data obtained from us or our services.
- Don’t transfer any data that you receive from us to any ad network, data broker or other advertising or monetization-related service.
- If you are acquired by or merge with a third party, you can continue to use our data only within your app.
- If you stop using the Automatic platform, promptly delete all data you have received from us.
- Give people control.
- Your app must have a privacy policy that fully explains what data you are collecting and how you will use that data.
- You should clearly state your app’s privacy policy in a place that is easy for users to find.
- Your app must comply with your privacy policy, and must also be in accordance with Automatic’s privacy policy.
- Provide meaningful customer support for your app, and make it easy for people to contact you.
- Delete all of a person’s data you have received from us if that person asks you to, unless you are required to keep it by law, regulation, or separate agreement with us.
- Respect proper use.
- If you want to use our logos or brand, follow the guidelines in the Automatic Brand Guide.
- Don’t sell, transfer or sublicense our code, APIs, or tools to anyone.
- Be honest about your relationship with Automatic when talking to the press or users. Comply with our PR Guidelines and get approval from us before issuing any formal press release or blog post mentioning Automatic.
- Name apps appropriately.
- Names containing the word Automatic will need special approval unless of the pre-approved form “[Your Company or Product]’s Integration for Automatic.”
- Do not use the company or product name of another entity that you do not control.
- Do not use profane, sexual, or other potentially offensive terms in your app name.
- Do not use a descriptive name that improperly describes your app’s functionality.
- Do not ever ask users for their Automatic password; that should only ever happen on the OAuth pages that Automatic serves.
- Follow the law.
- Don’t provide or promote content that infringes upon the rights of any third party.
- Ensure that you own or secure all rights necessary to display, distribute and deliver all content in your app.
- If your app contains content submitted or provided by third parties:
- In the United States, you must take all steps required to fall within the applicable safe harbors of the Digital Millennium Copyright Act including designating an agent to receive notices of claimed infringement, instituting a repeat infringer termination policy and implementing a notice and takedown process.
- In other countries, you must comply with local copyright laws and implement an appropriate notice and takedown process for when you receive a notice of claimed infringement.
- Comply with all applicable laws and regulations in the jurisdiction where your app is available.
- Do not expose Automatic or people who use Automatic to harm or legal liability as determined by us in our sole discretion.
- You agree to indemnify and hold us harmless from and against all damages, losses, and expenses of any kind (including reasonable legal fees and costs) related to any claim against us related to your service, actions, content or information.
Support
Legacy API Reference
Our v1 REST API documentation is still available for reference. It is no longer being developed and we do not recommend that you develop on it. It will remain active for some time and will eventually be fully deprecated.
Email Us
Shoot us a message with any questions and we’ll be happy to help: [email protected].