API Documentation

Let's dive right into the API documentation. If you're still unsure about what APIs are and how to get started, we highly recommend watching this video.

• Getting Started
• The Edmunds APIs at a Glance
• Available APIs
• Static Value Sets
• API Call Rate Limit
• Common Errors
• Known Issues

Getting Started

Before you you will be able go use the Edmunds API, you will need to read and agree to our Terms of Use.

Ready to rock and roll? Awesome.

1. Register an account
2.  Get your API Key(s) 
3. Read the API Documentation or test it in the API Console  

The Edmunds APIs at a Glance

All our API calls have the following format:

http://api.edmunds.com/{version}/{call path}?{call parameters}&fmt={format}&api_key={api_key}&callback={fn}

So let's break it down:

Now let's take a look at what lies within the braces within the API call.

Common Parameters

The following parameters may or may not be required in every single API call:

The {call path} and {call parameters} are specific to the API endpoints and will be called out explicitly for each endpoint.

Available APIs

The following APIs are currently available:

The Vehicle API

Everything you need to know about a vehicle from specs, features, photos, pricing, maintenace, and incentives to vehcile ratings, reviews, and VIN decoding capabilities. 

The Editorial API

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

The Inventory API (partner-only)

All the data you need to help build a meaningful automotive experience for dealerships and their customers

The Dealer API

Get dealership information, ratings and reviews. All dealership details are available through this API

Examples

Request 1:

Get all information on BMW M3 2011

http://api.edmunds.com/v1/api/vehicle/bmw/m3/2011?api_key={api_key}&fmt=json

Response 1:

{
    "modelYearHolder": [
        {
            "makeId": 200000081,
            "makeName": "BMW",
            "makeNiceName": "bmw",
            "modelId": "BMW_M3",
            "modelName": "M3",
            "modelNiceName": "m3",
            "id": 100531349,
            "styles": [
                {
                    "link": "/api/vehicle/style/101287988",
                    "publicationState": "NEW",
                    "id": "101287988",
                    "name": "4dr Sedan (4.0L 8cyl 6M)"
                },
                {
                    "link": "/api/vehicle/style/101287990",
                    "publicationState": "NEW",
                    "id": "101287990",
                    "name": "2dr Convertible (4.0L 8cyl 6M)"
                },
                {
                    "link": "/api/vehicle/style/101287989",
                    "publicationState": "NEW",
                    "id": "101287989",
                    "name": "2dr Coupe (4.0L 8cyl 6M)"
                }
            ],
            "newDefaultStyle": {
                "link": "/api/vehicle/style/101287988"
            },
            "equipment": [
                {
                    "link": "/api/vehicle/equipment/200074965"
                },
                {
                    "link": "/api/vehicle/equipment/200074964"
                },
                {
                    "link": "/api/vehicle/equipment/200074967"
                },
                {
                    "link": "/api/vehicle/equipment/200074992"
                }
            ],
            "subModels": [
                {
                    "identifier": "Sedan",
                    "name": "M3 Sedan",
                    "ruleType": "body",
                    "styleIds": [
                        101287988
                    ],
                    "publicationStates": [
                        "NEW"
                    ],
                    "submodelNewDefaultStyle": {
                        "link": "/api/vehicle/style/101287988"
                    }
                },
                {
                    "identifier": "Coupe",
                    "name": "M3 Coupe",
                    "ruleType": "body",
                    "styleIds": [
                        101287989
                    ],
                    "publicationStates": [
                        "NEW"
                    ],
                    "submodelNewDefaultStyle": {
                        "link": "/api/vehicle/style/101287989"
                    }
                },
                {
                    "identifier": "Convertible",
                    "name": "M3 Convertible",
                    "ruleType": "body",
                    "styleIds": [
                        101287990
                    ],
                    "publicationStates": [
                        "NEW"
                    ],
                    "submodelNewDefaultStyle": {
                        "link": "/api/vehicle/style/101287990"
                    }
                }
            ],
            "midYear": false,
            "year": 2011,
            "model": {
                "link": "/api/vehicle/bmw/m3",
                "id": "BMW_M3",
                "name": "M3"
            },
            "name": "2011",
            "attributeGroups": {
                "MAIN": {
                    "id": 1,
                    "name": "MAIN",
                    "attributes": {
                        "NAME": {
                            "id": 1,
                            "name": "NAME",
                            "value": "M3"
                        },
                        "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": "M030046"
                        }
                    }
                },
                "LEGACY": {
                    "id": 64,
                    "name": "LEGACY",
                    "attributes": {
                        "ED_MODEL_ID": {
                            "id": 3,
                            "name": "ED_MODEL_ID",
                            "value": "100531349"
                        }
                    }
                }
            },
            "categories": {
                "PRIMARY_BODY_TYPE": [
                    "Car"
                ],
                "Vehicle Size": [
                    "Midsize"
                ],
                "Vehicle Style": [
                    "Convertible",
                    "Sedan",
                    "Coupe"
                ],
                "Vehicle Type": [
                    "Car"
                ],
                "Tier Five  - Vehicle Market Perception": [
                    "Factory Tuner",
                    "Luxury",
                    "Performance",
                    "High-Performance"
                ]
            },
            "publicationStates": [
                "NEW"
            ]
        }
    ]
}

Request 2:

Get the True Market Value^tm on BMW M3 2011 4dr Sedan (4.0L 8cyl 6M)

http://api.edmunds.com/v1/api/tmv/tmvservice/calculatetypicallyequippedusedtmv?styleid=101287988&zip=90404&api_key={api_key}&fmt=json

Response 2:

{
    "tmv": {
        "certifiedUsedPrice": 0,
        "colorAdjustment": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        },
        "conditionAdjustment": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        },
        "estimatedTmv": false,
        "mileageAdjustment": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        },
        "nationalBasePrice": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        },
        "optionTMVPrices": {
            "200074977": {
                "baseInvoice": 2640,
                "baseMSRP": 2900,
                "deliveryCharges": 0,
                "estimateTmv": false,
                "tmv": 2713,
                "tmvRecommendedRating": 0,
                "usedPrivateParty": 0,
                "usedTmvRetail": 0,
                "usedTradeIn": 0
            },
            "200074983": {
                "baseInvoice": 955,
                "baseMSRP": 1050,
                "deliveryCharges": 0,
                "estimateTmv": false,
                "tmv": 982,
                "tmvRecommendedRating": 0,
                "usedPrivateParty": 0,
                "usedTmvRetail": 0,
                "usedTradeIn": 0
            },
            "200074993": {
                "baseInvoice": 365,
                "baseMSRP": 400,
                "deliveryCharges": 0,
                "estimateTmv": false,
                "tmv": 375,
                "tmvRecommendedRating": 0,
                "usedPrivateParty": 0,
                "usedTmvRetail": 0,
                "usedTradeIn": 0
            }
        },
        "regionalAdjustment": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        },
        "totalWithOptions": {
            "usedPrivateParty": 0,
            "usedTmvRetail": 0,
            "usedTradeIn": 0
        }
    }
}

Static Value Sets

Here's a list of values that will help you get the most of the Edmunds APIs.

Vehicle Types:

Vehicle Styles:

Vehicle Sizes:

API Call Rate Limit

All our APIs come with the standard 2 queries per second, and 5000 queries per day. Should an API offer a different call rate, we will note that out in the API's documentation page. Some API Keys might have different call rate limit. If you want us to increase your rate limit, please contact us at api [at] edmunds [dot] com.

Common Errors

While using our APIs, you might receive one or more of the following errors:

Sample Error Response

JSON Response:

{ "error": {"code":400, "message":"Bad Request"}} 

JSONP Response:

somefunction({ "error": {"code":400, "message":"Bad Request"}});

Known Issues

We are aware and working on the following issues:

• RESOLVED on 10/06/2011 - API response errors are formated in XML and not JSON. This breaks JSONP implementation of the API.