Api documentation

Api documentation

API Overview

API Overview
 
 

Page Content


Introduction

Welcome! To get you started, let’s go over the automotive datasets we’ve made available for you through the Edmunds API. Once you register for a key, you will be able to access the following datasets:

Dataset Description
Vehicle Specs Vehicle make/model/year/trim data, vehicle equipment, vehicle options, vehicle colors, etc.
Vehicle Pricing Edmunds.com TMV® (True Market Value®), Edmunds.com TCO® (True Cost to Own®), etc.
Vehicle Service Vehicle maintenance schedule, vehicle recalls, vehicle service bulletins, etc.
Vehicle Content Consumer reviews, editorial reviews, editorial articles, etc.
Vehicle Media Vehicle photos
Dealership Content Dealership info, consumer reviews, list of cars for sale, dealer pricing, etc.

These datasets are distributed across four distinct APIs: Vehicle API, Editorial API, Dealer API and Inventory API. A list of resources available under each API is on the left.

This overview covers the core concepts that you need to know before you could fully use the APIs to their potential. Once you have a good understanding of the API core concepts, you can then dig deeper into each API by visiting its dedicated overview page.

Back to top

Rate Limit

Access to our Open API is granted across three tiers, Exploratory, Enhanced, and Professional.

Exploratory (25 CPD) is for you to test and Explore the Edmunds API.

Enhanced (100 CPD) helps us to get to know who you are and what you are building with the Edmunds API.

Professional (100k CPD) is for users that have demonstrated they are good stewards of the Edmunds API, and would like to scale their use of Edmunds’ Data.

Exploratory

25 cpd | 5 cps - Open Access

All Edmunds API keys are issued with a default quota of 25 calls/day and 5 calls/second. This rate limit should provide sufficient access to test and explore the Edmunds API. Don’t forget to check out the API Console for testing and education.

Enhanced

100 cpd | 10 cps - Developers Must Request Access

If you would like to apply for enhanced access of our API, please contact us and be sure to select “Request Enhanced Access” In order to be granted Enhanced access and receive an increased rate limit, we need to verify the following:

Applications are reviewed every 2 weeks. When your application is approved, your rate limit will be increased to 100 calls/day.

Professional

100,000 cpd | 25 cps - Developers Must Request Access

Our professional access is reserved for partners that are approved by our Open API review board. If you would like to apply for Professional access of our API, please contact us and be sure to select “Request Professional Access” in order to receive access with an increased rate limit of 100,000 calls/day we will need to verify the following:

Applications are reviewed every 90 days. When your application is approved, your rate limit will be increased to 100,000 calls/day.

Back to top

Available Resources


AVAILABLE APIs
RESOURCE
ACCESS TIERS
Exploratory
25 CPD / 5 CPS
Enhanced
100 CPD / 10 CPS
Professional
100K CPD / 25 CPS
Partner
1m CPD / 25 CPS
Editorial API

Editorial API

Access to Edmunds.com’s quality editorial content from editor reviews to vehicle-specific articles.

See more>
EXPLORATORY
ENHANCED
PROFESSIONAL
PARTNERS
Inventory API

Inventory API

Find the vehicle detail for a given VIN (Vehicle Identification Number).

See more>
EXPLORATORY
ENHANCED
PROFESSIONAL
PARTNERS
Dealer API

Dealer API

Find dealers in a particular area or for a particular vehicle.

See more>
EXPLORATORY
ENHANCED
PROFESSIONAL
PARTNERS
Media API

Media API

Provides access to vehicles photo and video content.

See more>
EXPLORATORY
ENHANCED
PROFESSIONAL
PARTNERS

Although access to these APIs is free, their availability to developers varies based on the access tier to which the developer belongs. We currently offer four access tiers:

  • EXPLORATORY: All developers and companies start exploring here.
  • ENHANCED: Increased rate limit to start building your application.
  • PROFESSIONAL: Increased rate limits to help your application grow.
  • PARTNERS: Developers working with Edmunds.com on strategic products and applications that include the Edmunds.com data and content. If you’d like to become an Edmunds API Partner, please contact us .

Regardless of access tier, all developers using the Edmunds API need to read and agree to our Terms of Service.

Back to top

Data Hierarchy

Exploring a new API can be daunting. To make using our API enjoyable, easy, and fun, it’s important to understand a few things regarding how our data is structured and how our APIs work.

In order to retrieve most of the datasets we offer in the API, you will almost always need the car Model Year ID or the car Style ID. To get these IDs, you need to know at least the car make you’re interested in:

Car Make Car Model Car Model Year Car Trim Car Style

In the Useful API Calls section below, we’ll show you how to get both IDs in one API call!

Name Description
Car Make It’s either the name of the car’s manufacturer or, if the manufacturer has more than one operating unit, the name of that unit
Car Model A specific vehicle brand identified by a name or number (and which is usually further classified by trim or style level)
Car Model Year For a vehicle model, the calendar year designation assigned by the manufacturer to the annual version of that model
Car Style A style is the specific version of a particular model. Each style offers different levels of equipment and a unique price point. Manufacturers have their own way of determining styles and these are not necessarily comparable across models.

Here’s a list of the complete Edmunds Glossary.

Back to top

Data Constraints

  1. The history of the automobile goes back as early as 1769, but the Edmunds API dataset goes all the way back to 1990 and not further. This includes VIN decoding, so when decoding used VINs, keep in mind that error codes will return for vehicles that are older than 1990.
  2. At the moment, the API is focused on delivering data for vehicles which are/were sold to consumers in the United States of America, only.
  3. We also do not have comprehensive coverage of vehicles which were sold with the intent for commercial use.

It’s also important to note that our dataset goes all the way back to 1990 and not further. So if you’re looking for information on a 1981 DeLorean, you might be out of luck.

Back to top

URI Format

All API calls follow this format: {protocol}://api.edmunds.com/{endpoint}?fmt={response format}&api_key={API key}

Name Description Required? Default Value
protocol HTTP/HTTPS Yes http | https

Note: We recommend using the https when possible for extra security.

endpoint Path to API method Yes varies per API call

Note: Endpoints are documented under each API's resources and will include the endpoint's version as well as the API method

response format API response format Yes json | xml

Note: All API calls support json as the default response format. XML support is limited and will be noted in the endpoint documentation if the response format also supports XML. For JSONP support, you will need to add callback= to the query string and set it to the Javascript function that you have defined to handle the json response.

API key Authorized API Key Yes Get your API key

CORS Support

The API also supports Cross-Origin Resource Sharing (CORS) which allows cross-domain requests to be made by JavaScript on a web page. Such “cross-domain” requests would otherwise be forbidden by web browsers, per the same origin security policy. CORS is supported by all modern web browsers, and a full list of browser support can be found here.

Back to top

URI Examples

https://api.edmunds.com/api/vehicle/v2/makes?fmt=json&api_key=94tyghf85jdhshwge334

http://api.edmunds.com/api/vehicle/v2/lexus/models?fmt=json&api_key=94tyghf85jdhshwge334&callback=myFunction

https://api.edmunds.com/api/vehicle/v2/makes?fmt=json&api_key=94tyghf85jdhshwge334&state=new&view=full

Back to top

Error Codes and Handling

API errors occur for several reasons. Here’s a list of common errors and ways to troubleshoot them.

HTTP Status Description Troubleshooting
400 Bad Request Check the URL to make sure it has proper syntax
401 Unauthorized You are using the wrong API key or the key isn’t active
403 Forbidden You are not authorized to access this resource, sorry.
404 Not Found Check the URL path for typos
502 Bad Gateway If this persists, check our API Status. It might be an issue we’re addressing
503 Service Unavailable If this persists, check our API Status. It might be an issue we’re addressing
504 Gateway Timeout If this persists, check our API Status. It might be an issue we’re addressing

If an error persists and you can’t resolve it, please contact us and let us know.

When an error occurs, you should get the following response:

{
	"status": "http_status",
	"errorType": "error_description",
	"message": "some_message",
	"moreInfoUrl": "http://developer.edmunds.com"
}

Back to top

Useful API Calls

As mentioned above, car style IDs and Model Year IDs are important to retrieve other datasets in the API.

To get the Model Year IDs for all new makes, use the following API call:

http://api.edmunds.com/api/vehicle/v2/makes?fmt=json&state=new&api_key={your API key}

In the response of that call, you will find the following object:

{
	"id": 100538949,
	"year": 2013
}

The id key in this object is the Model Year ID.

To get the style IDs for a specific car make, let’s use Lexus as an example, use the following API call:

http://api.edmunds.com/api/vehicle/v2/lexus/models?fmt=json&api_key={your vehicle api key}

In the response of that call, you will find the following object:

{
	"id": 101286113,
	"name": "4dr Hatchback (1.8L 4cyl gas/electric hybrid CVT)",
	"submodel": {
		"body": "Hatchback",
		"modelName": "CT 200h Hatchback"
	},
	"trim": "Base"
}

The id key in this object is the Style ID.

More on these endpoints in the Spec: Make and Spec: Model resources under the Vehicle API.

Back to top

SDKs and Code Samples

Our Javascript and Python SDKs are a great way to start integrating our API into your application and work with many examples as well. For other SDKs and code samples, visit our Github home.

Back to top

Pedal to The Metal!

If you’ve made it this far, congratulations! You’re way on your way to rocking the API!

This is also a good time to make sure you’re all set with an account and a key for the API(s) you want use. If you still haven’t gotten your API key, get a key now so you can start building in no time!

All set? Awesome. Why not start making live API calls right now by using the API Console. You won’t need to write a single line of code to do so! Seriously. It’s an interactive tool built by our friends at Mashery to help you get a sense of our data before investing time and effort coding against it.

Once you’re comfortable with our APIs, you can start coding against it with confidence. We have a Javascript SDK handy to help you start integrating the API into your pages in no time.

Still have questions? Don’t hesitate to contact us . We love to hear from you!

Back to top