- Previous: The Editorial API V1
- Up: API Documentation
- Next: Model Year Repository
The Vehicle API V1
Understanding the Vehicles API
The Vehicles API encapsulates the REST calls that a developer uses to get automotive make/model/style information from the Edmunds data repository. The vehicles in Vehicles API are organized in a hierarchical structure. At the top of the Vehicles API hierarchy is the Model Year, followed subordinately by the Make and Model. One you get ot the Model level, you can access Style, Equipment, Submodels, Attribute Groups, Categories, Features, Maintenance and Photo information relevant to the particular Model.
Also, from the Style level you can drill down into True Cost of Ownership (TCO), True Market Value (TMV) and Tax information.
The Quick Start that follows gives you a fast look at how to use the Vehicle API to get vehicle information. If you want to dig deeper to learn about all of the calls available for working with vehicles information, check out the API Resources section.
Quick Start
How to get a list of all Makes the current Model Year:
The following REST call retreives a list of all the vehicle Make available on Edmunds data repository for the current calendar year.
[Please note that the REST call does not need to specficy Model Year because current Model Year is the implicit default.]
URL
http://api.edmunds.com/{version}/api/vehicle-directory-ajax/findmakes?api_key=xxxxxxxxxxx&fmt=jsonResult
{
"makes": {
"Acura": {
"id": 200002038,
"link": "/vehicle-directory-ajax/findmakemodels/?make=Acura&fmt=json&yearFormat=expanded",
"name": "Acura",
"niceName": "acura"
},
"Aston Martin": {
"id": 200001769,
"link": "/vehicle-directory-ajax/findmakemodels/?make=Aston Martin&fmt=json&yearFormat=expanded",
"name": "Aston Martin",
"niceName": "aston-martin"
},
...
...
...
"Volkswagen": {
"id": 200000238,
"link": "/vehicle-directory-ajax/findmakemodels/?make=Volkswagen&fmt=json&yearFormat=expanded",
"name": "Volkswagen",
"niceName": "volkswagen"
},
"Volvo": {
"id": 200010382,
"link": "/vehicle-directory-ajax/findmakemodels/?make=Volvo&fmt=json&yearFormat=expanded",
"name": "Volvo",
"niceName": "volvo"
}
}
}
How to get a list of all Models for a particular vehicle makes:
To grab a list of all Models associated with a particular vehicle Make, in this case an Aston-Martin, supply the "niceName" value of the Make in the URL
[Please note that a nice name is.....]
URL
http://api.edmunds.com/{version}/api/vehicle-directory-ajax/findmakemodels?make=aston-martin&api_key=xxxxxxxxxxx&fmt=jsonResult
{
"models": {
"db7:convertible": {
"id": 1,
"link": "/aston-martin/db7/",
"model": "db7",
"modelname": "DB7",
"name": "DB7 Convertible",
"submodel": "convertible",
"years": {
"USED": [
2003,
2002,
2001
]
}
},
"db7:coupe": {
"id": 3,
"link": "/aston-martin/db7/",
"model": "db7",
"modelname": "DB7",
"name": "DB7 Coupe",
"submodel": "coupe",
"years": {
"USED": [
2003,
2002,
2001
]
}
},
...
...
...
"virage:convertible": {
"id": 18,
"link": "/aston-martin/virage/",
"model": "virage",
"modelname": "Virage",
"name": "Virage Convertible",
"submodel": "convertible",
"years": {
"NEW": [
2011
]
}
},
"virage:coupe": {
"id": 19,
"link": "/aston-martin/virage/",
"model": "virage",
"modelname": "Virage",
"name": "Virage Coupe",
"submodel": "coupe",
"years": {
"NEW": [
2011
]
}
}
}
}
How to get details about a specific Make/Model/Year vehicle:
If you already know the Make/Model/Year of the vehicle you are interested in, you can get subordinate details such as Style, Equipment, and Categories information as shown in the following REST call for a 2011 Aston Martin Virage.
URL
http://api.edmunds.com/{version}/api/vehicle/aston-martin/virage/2011?api_key=xxxxxxxxxxx&fmt=jsonResult
{
"modelYearHolder": [
{
"makeId": 200001769,
"makeName": "Aston Martin",
"makeNiceName": "astonmartin",
"modelId": "Aston_Martin_Virage",
"modelName": "Virage",
"modelNiceName": "virage",
"id": 100535109,
"styles": [
{
"link": "/api/vehicle/style/101381829",
"publicationState": "NEW",
"id": "101381829",
"name": "Volante 2dr Convertible (5.9L 12cyl 6A)"
},
{
"link": "/api/vehicle/style/101381819",
"publicationState": "NEW",
"id": "101381819",
"name": "2dr Coupe (5.9L 12cyl 6A)"
}
],
"newDefaultStyle": {
"link": "/api/vehicle/style/101381819"
},
"equipment": [
{
"link": "/api/vehicle/equipment/200373507"
},
{
"link": "/api/vehicle/equipment/200373500"
},
...
...
...
{
"link": "/api/vehicle/equipment/200373699"
},
{
"link": "/api/vehicle/equipment/200373517"
}
],
"subModels": [
{
"identifier": "Convertible",
"name": "Virage Convertible",
"ruleType": "body",
"styleIds": [
101381829
],
"publicationStates": [
"NEW"
],
"submodelNewDefaultStyle": {
"link": "/api/vehicle/style/101381829"
}
},
{
"identifier": "Coupe",
"name": "Virage Coupe",
"ruleType": "body",
"styleIds": [
101381819
],
"publicationStates": [
"NEW"
],
"submodelNewDefaultStyle": {
"link": "/api/vehicle/style/101381819"
}
}
],
"midYear": false,
"year": 2011,
"model": {
"link": "/api/vehicle/aston-martin/virage",
"id": "Aston_Martin_Virage",
"name": "Virage"
},
"name": "2011",
"attributeGroups": {
"MAIN": {
"id": 1,
"name": "MAIN",
"attributes": {
"NAME": {
"id": 1,
"name": "NAME",
"value": "Virage"
},
"USE_IN_NEW": {
"id": 10,
"name": "USE_IN_NEW",
"value": "Y"
},
"YEAR": {
"id": 2,
"name": "YEAR",
"value": "2011"
},
"USE_IN_USED": {
"id": 11,
"name": "USE_IN_USED",
"value": "N"
},
"USE_IN_PRE_PRODUCTION": {
"id": 12,
"name": "USE_IN_PRE_PRODUCTION",
"value": "N"
},
"USE_IN_FUTURE": {
"id": 595,
"name": "USE_IN_FUTURE",
"value": "N"
},
"MODEL_LINK_CODE": {
"id": 20,
"name": "MODEL_LINK_CODE",
"value": "M120029"
}
}
},
"LEGACY": {
"id": 64,
"name": "LEGACY",
"attributes": {
"ED_MODEL_ID": {
"id": 3,
"name": "ED_MODEL_ID",
"value": "100535109"
}
}
}
},
"categories": {
"PRIMARY_BODY_TYPE": [
"Car"
],
"Vehicle Size": [
"Midsize"
],
"Vehicle Style": [
"Convertible",
"Coupe"
],
"Vehicle Type": [
"Car"
],
"Tier Five - Vehicle Market Perception": [
"Exotic",
"Performance",
"High-Performance"
]
},
"publicationStates": [
"NEW"
]
}
]
}
API Resources
Make Year Repository
The Model Year repository is the root entity of the Edmunds data repository. All vehicles data is organized according to Model Year.
Make Repository
The Makes repository provides information according to the Make of a vehicle.
Model Repository
The Models Repository provides Model information about a particular Make.
Style Repository
The Styles Repository provides information about a Style(s) associated with a given Make according to Model and Model Year or by ModelYear ID. Usually a Make will have multiple Styles.
True Market Valuetm
The True Market Valuetm (TMV) Repository provides True Market Valuetm information for a given vehcile by region.
TMV is the average price that a car sells for within a particular region. TMV is adjusted for options, the vehicle's color and associated incentives. TMV figures are based on the actual sales of other vehicles of its kind in the given region. The figure is then adjusted further for accuracy using sophisticated calculations designed by mathematicians at Edmunds.com.
Incentive Repository
The Incentives repository provides information according to the available Vehicle Incentives offered by automotive manufacturers.
API Key Requirement
You need to apply for an API Key to use this API suite.
- Previous: The Editorial API V1
- Up: API Documentation
- Next: Model Year Repository
3 Comments
om – 7 months ago
what should i write replace of version in api
Ismail Elshareef – 5 months ago
V1
Bachynskyi – 2 months ago
Hi! Where I can take VIN?
Please sign in to post a comment.