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

Available Resources

AVAILABLE APIs
RESOURCE
Editorial API

Editorial API

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

See more>
Inventory API

Inventory API

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

See more>
Dealer API

Dealer API

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

See more>
Media API

Media API

Provides access to vehicles photo and video content.

See more>

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

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  
503 Service Unavailable  
504 Gateway Timeout  

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:

  1. {
  2. "status": "http_status",
  3. "errorType": "error_description",
  4. "message": "some_message",
  5. "moreInfoUrl": "http://developer.edmunds.com"
  6. }

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:

  1. {
  2. "id": 100538949,
  3. "year": 2013
  4. }

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:

  1. {
  2. "id": 101286113,
  3. "name": "4dr Hatchback (1.8L 4cyl gas/electric hybrid CVT)",
  4. "submodel": {
  5. "body": "Hatchback",
  6. "modelName": "CT 200h Hatchback"
  7. },
  8. "trim": "Base"
  9. }

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!

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