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.
All developers using the Edmunds API need to read and agree to our Terms of Service.
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.
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.
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 |
API key
|
Authorized API Key | Yes |
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.
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
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:
{
"status": "http_status",
"errorType": "error_description",
"message": "some_message",
"moreInfoUrl": "http://developer.edmunds.com"
}
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.
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.
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!