The Vehicle API

Understanding The Vehicle API

The Vehicle API encapsulates the following car-specific resources: (Please note that we will be using vehicle and car interchangeably)

SPECIFICATION (SPEC) SERVICEPRICING CONTENT MEDIA
Vehicle Make Vehicle Maintenace  True Cost to Own® (TCO®) Edmunds Car Ratings Vehicle Photos
Vehicle Model Vehicle Recalls True Market Value® ( TMV®) Vehicle Rating and Reviews
Vehicle Model Year Vehicle Service Bulletins Incentives and Rebates
Vehicle Style Service Labor Rates
Vehicle Options
Vehicle Colors
Vehicle Equipment
Vehicle VIN Decoding

By now you, you should be familiar with the Edmunds API data hierarchy that we discussed on the API Overview page. Understanding the concepts covered on that page will make it easier for you to take advantage of the array of datasets we make avialable through the API. 

In order to retrieve most of the datasets we offer in the API, you will almost always need the car Style ID or the car Model Year 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!

  • 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.

Also, once you have the vehicle's Style ID, you could then get its True Cost to Own® (TCO®), True Market Value® (TMV®), photos, options, equipment, colors, incentives, rebates, ...etc.

Quick Start

Let's get right to it, shall we? Here's a few REST calls that should get you started using the API with ease. You could copy and paste these calls into your browser, add your API key to them and see them in action! Better yet, you could use our API Console to make live API calls of your own. Once  you're comfortable with these calls, you should think about downloading our Javascript SDK. It will make your development life much better :)

Example 1: Get a list of all car makes

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

Example 2: Get a list of all new car makes

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

Example 3: Get model, model year, style and trim data for Honda

https://api.edmunds.com/api/vehicle/v2/honda/models?fmt=json&api_key={your API key}

Example 4: Get model, model year, style and trim data for 2001 Honda

https://api.edmunds.com/api/vehicle/v2/honda/models?year=2001&fmt=json&api_key={your API key}

Example 5: Get the total number of all new Acura models in the Edmunds data

https://api.edmunds.com/api/vehicle/v2/acura/models/count?state=new&fmt=json&api_key={your API key}

Example 6: Get a list of styles for 2001 Honda Accord

https://api.edmunds.com/api/vehicle/v2/honda/accord/2001?fmt=json&api_key={your API key}

Example 7: Get a list of Maintenance Schedules for 2001 Honda Accord

https://api.edmunds.com/v1/api/maintenance/actionrepository/findbymodelyearid?modelyearid=100537293&fmt=json&api_key={your API key}

Example 8: Get all photos for 2001 Honda Accord EX 4dr Sedan (2.3L 4cyl 4A)

https://api.edmunds.com/v1/api/vehiclephoto/service/findphotosbystyleid?styleId=100001210&fmt=json&api_key={your API key}

Example 9: Get the TMV® for 2001 Honda Accord EX 4dr Sedan (2.3L 4cyl 4A) w/ Outstanding condition and 25,000 miles in the 90069 area

https://api.edmunds.com/v1/api/tmv/tmvservice/calculateusedtmv?styleid=100001210&condition=Outstanding&mileage=25000&zip=90069&fmt=json&api_key={your API key}

These examples should give you an idea of what you could accomplish with the Vehicle API

27 Comments

  1. om2 years ago

    what should i write replace of version in api

  2. Ismail Elshareef2 years ago

    V1

  3. Bachynskyi1 year ago

    Hi! Where I can take VIN?

  4. benchmark12 months ago

    Hi.. Is it possible to get all the make, model and year at once.Is there any link available for that.

    Thank you.

  5. Ismail Elshareef12 months ago

    Yes. If you know the make, you can get all relevant information in one call using one of our new Vehicle API 2.0 endpoints: http://api.edmunds.com/api/vehicle/v2/acura/models?fmt=json&api_key{vehicle api key}

  6. benchmark12 months ago

    Hi thanks for your response. I saw your own app for iPhone and it was fantastic. In that, you are loading all the datas(make,model and year) when app launched and using those datas in future. It seems they are retrieving all these datas in a single call. Is there any thing like that? currently, I am getting all make in one call and after selecting make, I am getting its model and year.So its delays the flow.

    Also, is there any way to get image urls without style ids? Because, for this too, we have to send all three parameters(make,model,year) for getting style ids first and then send that style id to get image urls.And finally, these image urls have to be used to display image.

    Is there any other way to get images and details of models without this long process?

    Please suggest which is the best method to integrate edmunds API to mobile app.

    Thank you.

  7. Ismail Elshareef12 months ago

    Hi,

    Yes, you can use this call http://api.edmunds.com/api/vehicle/v2/makes?fmt=json&api_key={vehicle api key}

    To get only new cars, use this http://api.edmunds.com/api/vehicle/v2/makes?fmt=json&api_key={vehicle api key}&state=new

    Use cars only http://api.edmunds.com/api/vehicle/v2/makes?fmt=json&api_key={vehicle api key}&state=used

    Unfortunately, we don't have a way to look up images by anything other than style id. That will change in API 2.0.

    I would use the links above and once the user chooses a car make, make another call to get the styles ...etc. Once the user selects a style, get the photos.

    Hope this helps.

    Thanks!

  8. benchmark12 months ago

    Thank you!!! Still we are facing some problem in the above links you given. 1. We are getting all the make and its models and year.But not mentioned whether its a used or new car anywhere in that. 2. To get style ID, we have to call again with three parameters(make.model,year).Then again calling with style id only we are able to get image urls. Please provide any easy call to get image url. And documentation not clear enough. 3.What about version2? Any new features?

    Thank you.

  9. bluecognit12 months ago

    im getting

    { "error": {"code":403, "message":"Developer Inactive"} }

  10. Ismail Elshareef12 months ago

    Could you send us the API call you're using to api at edmunds.com?

    Thanks!

  11. Bob Caligiuri11 months ago

    Here is an API call that gets the code 403 error:

    http://api.edmunds.com/v1/api/vehicle/modelyearrepository/foryearmakemodel?make=acura&model=mdx&year=2011&api_key=XXXXX&fmt=json

    Using V1 get an XML error: This XML file does not appear to have any style information associated with it. The document tree is shown below. <h1>596 Service Not Found</h1>

    Any help would be appreciated:

  12. Ismail Elshareef11 months ago

    Hi Bob,

    We're rolling out the new versions of Make and Model resources for the Vehicle API. Check it out live on the API Console http://developer.edmunds.com/io-docs

    Please note that the documentation hasn't yet been updated to reflect that change. I trust you will find the new endpoints extremely simple to use and much more intuitive than what we had in version 1.

  13. AA_Joe11 months ago

    Example 4: Get model, model year, style and trim data for 2001 Honda

    https://api.edmunds.com/api/vehicle/v2/honda/models?year=2001&fmt=json&api_key={your API key}

    is incorrect. The correct api call is:

    https://api.edmunds.com/api/vehicle/v2/honda?year=2001&fmt=json&api_key={your API key}

  14. Ismail Elshareef11 months ago

    AA_Joe,

    Sorry, but that's incorrect. The call you mentioned doesn't return style and trim data.

  15. AA_Joe11 months ago

    Ah, my bad. I was trying to get style and trim for a specific model so I had to replace 'models' with that model nicename.

    This gives the appropriate style and trim data for a honda ACCORD 2001

    https://api.edmunds.com/api/vehicle/v2/honda/accord?year=2001&fmt=json&api_key={stuffs}

  16. AA_Joe11 months ago

    Heh. Here's an interesting bug for you. The keyword for the api to show the trim data for all models is 'models' but the Tesla Motor Corp calls their model a 'Model S' which your system automatically changes to the nice name 'models'. See the problem here? http://screencast.com/t/78y0rN8Ifk I have a script that is intended to get a model specific response but when it tries to get the model specific response for the Tesla Model S, it gets the generic response for all models made by Tesla and my script fails.

  17. Ismail Elshareef11 months ago

    Very interesting. Thanks for the heads up. We're working on it.

  18. michaelrbock11 months ago

    AA_Joe, the obligatory XKCD: http://xkcd.com/327/

  19. Hallar Zarubin10 months ago

    Where do the car features(Exteriror, Safety, Interior) come from that are being displayed under the cars Specs & Features tab? I can't find the representation under the Vechicle API.

  20. michaelrbock10 months ago

    Hallar Zarubin, Please see our new v2 API and documentation at http://developer.edmunds.com/. Specifically, you can find info about car features such as the exterior and interior at the Color and Options spec endpoint. EDIT: Please see Ismail's comment below for clarification. The Color and Options spec endpoint only provides "optional" options, while the equipment endpoint can provide the list of standard features.

  21. Hallar Zarubin10 months ago

    Color and Options spec endpoint. seems to give me only the list of optional features but not the list of standard features.

  22. Ismail Elshareef10 months ago

    The options endpoints are for "optional" options. Standard features could be found by querying the equipment endpoint: http://www.edmunds.com/api/vehicle/v2/styles/{style ID}/equipment?availability=standard

    That gives you a list of standard features/equipment that come with the car.

  23. Hallar Zarubin10 months ago

    The Equipment API does not provide the features in the same human readable format as it is displayed on Edmunds.com. The API gives me the attributes in name:value pairs which do not seem to match the represtation on the website. Are there certain rules how the attributes should be combined? Also the attributes don\t have a refrence to subgroups.

  24. michaelrbock10 months ago

    Hi Hallar,

    Yes, the API returns the data in JSON format. You can see the exact response format for the equipment API here: http://developer.edmunds.com/api-documentation/vehicle/spec_equipment/v2/01_by_style/api-response.html and also see a sample request and response. The attributes are grouped under "equipmentType", "availability", and "name" (i.e. Equipment Name), and a full list of possible values are presented here: http://developer.edmunds.com/api-documentation/vehicle/spec_equipment/v2/index.html

    So for example, in the response for equipment you might find an object with the name "AIR_CONDITIONING", a type of "OTHER", availability "STANDARD" and then a list of attribute objects (each with a "name" and "value") pertaining to the air conditioning.

    Hopefully that helps. If you are noticing discrepancies between the API and the website, can you please email api@edmunds.com with the exact call you are making and the discrepancy you notice. Thanks a lot!

  25. Hallar Zarubin8 months ago

    Some of equipmentNames do not follow the same nomenclature as stated in http://developer.edmunds.com/api-documentation/vehicle/spec_equipment/v2/index.html . Example: ENGINE = Engine, AUDIO_SYSTEM = Audio System, WARRANTY = Warranty. Are these going to fixed?

  26. michaelrbock8 months ago

    Hi Hallar,

    We don't maintain this old documentation anymore, our new documentation is available at http://developer.edmunds.com/api-documentation/overview/index.html

    Could you please post your question on our forums that we maintain here: http://edmunds.mashery.com/forum and also include one or more sample API calls (without including your API key) you made where you found this error? Thanks!

  27. parkash5 months ago

    Hi Hallar,

    How to getting the default image of particular model.

Please sign in to post a comment.