Model Year Repository

The Model Year repository is the root entity of the Edmunds data repository. All vehicles data is organized according to Model Year.

Go to:

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/{method}

Response Format top

All method responses are JSON objects with a root property called, modelYearHolder. The value of modelYearHolder is an array of Model Year objects:

{
    "modelYearHolder": [
        model_object_1,
        model_object_2,
        model_object_3, 
        ....
        ....
     ]
}

Each Model Year object is a JSON object in the following format:

{
    "makeId": [integer],
    "makeName": [string]
    "makeNiceName": [string],
    "modelId": [string],
    "modelName": [string],
    "modelNiceName": [string],
    "id": [integer],
    "styles": [
        style_object_1,
        style_object_2,
        ...
    ],
    "usedDefaultStyle: [object],
    "equipment": [array],
    "name": [integer],
    "make": [object],
    "models": [object],
    "attributionGroups": [object]
    "categories": [object],
    "publicationStates": [object],
    "subModels": [object]
}

The properties of the Model Year object are:

  • makeId: The make ID
  • makeName: The name of the vehicle make
  • makeNiceName: The make's nice name, or URL-friendly name
  • id: The model ID
  • name: The model name
  • niceName: The model's nice name, or URL-friendly name
  • make: An object that has the API link to the vehicle make details
  • modelYears: An array of model year objects
  • attributeGroups: [description]
  • categories: The model various types
  • publicationStates: An array of available publication states
  • subModels: List of available submidels

Sample Requesttop

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/foryearmakemodel?make=acura&model=mdx&year=2011&api_key=xxxxxxxxxx&fmt=json

Sample Response

{
    "modelYearHolder": [
        {
            "makeId": 200002038,
            "makeName": "Acura",
            "makeNiceName": "acura",
            "modelId": "Acura_MDX",
            "modelName": "MDX",
            "modelNiceName": "mdx",
            "id": 100533210,
            "styles": [
                {
                    "link": "/api/vehicle/style/101355914",
                    "publicationState": "NEW_USED",
                    "id": "101355914",
                    "name": "4dr SUV AWD w/Advance, Entertainment Package (3.7L 6cyl 6A)"
                },
                {
                    "link": "/api/vehicle/style/101355913",
                    "publicationState": "NEW_USED",
                    "id": "101355913",
                    "name": "4dr SUV AWD w/Advance Package (3.7L 6cyl 6A)"
                },
                {
                    "link": "/api/vehicle/style/101355910",
                    "publicationState": "NEW_USED",
                    "id": "101355910",
                    "name": "4dr SUV AWD (3.7L 6cyl 6A)"
                },
                {
                    "link": "/api/vehicle/style/101355912",
                    "publicationState": "NEW_USED",
                    "id": "101355912",
                    "name": "4dr SUV AWD w/Technology, Entertainment Package (3.7L 6cyl 6A)"
                },
                {
                    "link": "/api/vehicle/style/101355911",
                    "publicationState": "NEW_USED",
                    "id": "101355911",
                    "name": "4dr SUV AWD w/Technology Package (3.7L 6cyl 6A)"
                }
            ],
            "newDefaultStyle": {
                "link": "/api/vehicle/style/101355910"
            },
            "usedDefaultStyle": {
                "link": "/api/vehicle/style/101355910"
            },
            "equipment": [
                {
                    "link": "/api/vehicle/equipment/200351261"
                },
                {
                    "link": "/api/vehicle/equipment/200351260"
                },
                {
                    "link": "/api/vehicle/equipment/200351217"
                },
                {
                    "link": "/api/vehicle/equipment/200351216"
                },
                {
                    "link": "/api/vehicle/equipment/200351215"
                },
                {
                    "link": "/api/vehicle/equipment/200351214"
                },
                {
                    "link": "/api/vehicle/equipment/200351219"
                },
                {
                    "link": "/api/vehicle/equipment/200351218"
                },
                {
                    "link": "/api/vehicle/equipment/200351258"
                },
                {
                    "link": "/api/vehicle/equipment/200351259"
                },
                {
                    "link": "/api/vehicle/equipment/200351254"
                },
                {
                    "link": "/api/vehicle/equipment/200351255"
                },
                {
                    "link": "/api/vehicle/equipment/200351256"
                },
                {
                    "link": "/api/vehicle/equipment/200351257"
                },
                {
                    "link": "/api/vehicle/equipment/200351250"
                },
                {
                    "link": "/api/vehicle/equipment/200351251"
                },
                {
                    "link": "/api/vehicle/equipment/200351252"
                },
                {
                    "link": "/api/vehicle/equipment/200351253"
                },
                {
                    "link": "/api/vehicle/equipment/200351220"
                },
                {
                    "link": "/api/vehicle/equipment/200351222"
                },
                {
                    "link": "/api/vehicle/equipment/200351221"
                },
                {
                    "link": "/api/vehicle/equipment/200351224"
                },
                {
                    "link": "/api/vehicle/equipment/200351223"
                },
                {
                    "link": "/api/vehicle/equipment/200351226"
                },
                {
                    "link": "/api/vehicle/equipment/200351225"
                },
                {
                    "link": "/api/vehicle/equipment/200351228"
                },
                {
                    "link": "/api/vehicle/equipment/200351227"
                },
                {
                    "link": "/api/vehicle/equipment/200351229"
                },
                {
                    "link": "/api/vehicle/equipment/200374621"
                },
                {
                    "link": "/api/vehicle/equipment/200351235"
                },
                {
                    "link": "/api/vehicle/equipment/200351234"
                },
                {
                    "link": "/api/vehicle/equipment/200351233"
                },
                {
                    "link": "/api/vehicle/equipment/200351232"
                },
                {
                    "link": "/api/vehicle/equipment/200351231"
                },
                {
                    "link": "/api/vehicle/equipment/200351230"
                },
                {
                    "link": "/api/vehicle/equipment/200351239"
                },
                {
                    "link": "/api/vehicle/equipment/200351238"
                },
                {
                    "link": "/api/vehicle/equipment/200351237"
                },
                {
                    "link": "/api/vehicle/equipment/200351236"
                },
                {
                    "link": "/api/vehicle/equipment/200371244"
                },
                {
                    "link": "/api/vehicle/equipment/200351244"
                },
                {
                    "link": "/api/vehicle/equipment/200351243"
                },
                {
                    "link": "/api/vehicle/equipment/200351246"
                },
                {
                    "link": "/api/vehicle/equipment/200351245"
                },
                {
                    "link": "/api/vehicle/equipment/200351240"
                },
                {
                    "link": "/api/vehicle/equipment/200351242"
                },
                {
                    "link": "/api/vehicle/equipment/200351241"
                },
                {
                    "link": "/api/vehicle/equipment/200351248"
                },
                {
                    "link": "/api/vehicle/equipment/200351247"
                },
                {
                    "link": "/api/vehicle/equipment/200351249"
                }
            ],
            "subModels": [
                {
                    "identifier": "SUV",
                    "name": "MDX SUV",
                    "ruleType": "",
                    "styleIds": [
                        101355914,
                        101355913,
                        101355912,
                        101355911,
                        101355910
                    ],
                    "publicationStates": [
                        "NEW_USED"
                    ],
                    "submodelNewDefaultStyle": {
                        "link": "/api/vehicle/style/101355910"
                    },
                    "submodelUsedDefaultStyle": {
                        "link": "/api/vehicle/style/101355910"
                    }
                }
            ],
            "midYear": false,
            "year": 2011,
            "dateAvailable": null,
            "model": {
                "link": "/api/vehicle/acura/mdx",
                "id": "Acura_MDX",
                "name": "MDX"
            },
            "name": "2011",
            "attributeGroups": {
                "RELIABILITY_RATINGS": {
                    "id": -100,
                    "name": "RELIABILITY_RATINGS",
                    "attributes": {
                        "POWERTRAIN_QUALITY_MECHANICAL": {
                            "id": 0,
                            "name": "POWERTRAIN_QUALITY_MECHANICAL",
                            "value": "3.5"
                        },
                        "OVERALL_QUALITY_DESIGN": {
                            "id": 0,
                            "name": "OVERALL_QUALITY_DESIGN",
                            "value": "3.5"
                        },
                        "OVERALL_QUALITY": {
                            "id": 0,
                            "name": "OVERALL_QUALITY",
                            "value": "4.0"
                        },
                        "OVERALL_QUALITY_MECHANICAL": {
                            "id": 0,
                            "name": "OVERALL_QUALITY_MECHANICAL",
                            "value": "4.0"
                        },
                        "POWERTRAIN_QUALITY_DESIGN": {
                            "id": 0,
                            "name": "POWERTRAIN_QUALITY_DESIGN",
                            "value": "3.0"
                        },
                        "FEATURES_AND_ACCESS_QUALITY_DESIGN": {
                            "id": 0,
                            "name": "FEATURES_AND_ACCESS_QUALITY_DESIGN",
                            "value": "3.0"
                        },
                        "BODY_AND_INTERIOR_QUALITY_MECHANICAL": {
                            "id": 0,
                            "name": "BODY_AND_INTERIOR_QUALITY_MECHANICAL",
                            "value": "4.0"
                        },
                        "FEATURES_AND_ACCESS_QUALITY_MECHANICAL": {
                            "id": 0,
                            "name": "FEATURES_AND_ACCESS_QUALITY_MECHANICAL",
                            "value": "4.0"
                        },
                        "BODY_AND_INTERIOR_QUALITY_DESIGN": {
                            "id": 0,
                            "name": "BODY_AND_INTERIOR_QUALITY_DESIGN",
                            "value": "5.0"
                        }
                    }
                },
                "MAIN": {
                    "id": 1,
                    "name": "MAIN",
                    "attributes": {
                        "NAME": {
                            "id": 1,
                            "name": "NAME",
                            "value": "MDX"
                        },
                        "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": "Y"
                        },
                        "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": "M030004"
                        }
                    }
                },
                "LEGACY": {
                    "id": 64,
                    "name": "LEGACY",
                    "attributes": {
                        "ED_MODEL_ID": {
                            "id": 3,
                            "name": "ED_MODEL_ID",
                            "value": "100533210"
                        }
                    }
                }
            },
            "categories": {
                "Crossover": [
                    "Crossover"
                ],
                "PRIMARY_BODY_TYPE": [
                    "SUV"
                ],
                "Vehicle Size": [
                    "Midsize"
                ],
                "Vehicle Style": [
                    "4dr SUV"
                ],
                "Vehicle Type": [
                    "SUV"
                ],
                "Tier Five  - Vehicle Market Perception": [
                    "Crossover",
                    "Luxury"
                ]
            },
            "publicationStates": [
                "NEW_USED"
            ]
        }
    ]
}

 

Available Methodstop

MethodDescription
findbyid

Get details on a specifc vehicle by its model year ID

finddistinctyearwithnew

 Get a list of years under which there are new vehicle listings
finddistinctyearwithneworused Get a list of years under which there are new or used vehicle listings
finddistinctyearwithused Get a list of years under which there are used vehicle listings
findfuturemodelyearsbymodelid Get a list of future model years by the model ID
findmodelyearsbymakeandyear Get a list of model years for a specific make and year
findmodelyearsbymakemodel Get a list of model years for a specific make and model
findnewandusedmodelyearsbymakeidandyear Get a list of new and used model years for a specific make ID and year
findnewmodelyearsbymodelid Get a list of new model years by the model ID
findusedmodelyearsbymodelid Get a list of used model years by the model ID
findyearsbycategoryandpublicationstate Get a list of model years for a specific category and publication state
formodelid Get a list of model years by the model ID
foryearmakemodel Get a list of model years for a specific make, model and year

 

Method: findbyid

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findbyid?id=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

id

Model Year ID

 Yes

Method: finddistinctyearwithnew

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/finddistinctyearwithnew?api_key=xxxxxxxxxx&fmt=json

Parameters

None.

Method: finddistinctyearwithneworused

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/finddistinctyearwithneworused?api_key=xxxxxxxxxx&fmt=json

Parameters

None.

Method: finddistinctyearwithused

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/finddistinctyearwithused?api_key=xxxxxxxxxx&fmt=json

Parameters

None.

Method: findfuturemodelyearsbymodelid

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findfuturemodelyearsbymodelid?modelId=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

modelId

The model ID

 Yes

Method: findmodelyearsbymakeandyear

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findmodelyearsbymakeandyear?make=xxx&year=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

make

The make name (use niceName value)

 Yes
year

The year of interest

 Yes

Method: findmodelyearsbymakemodel

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findmodelyearsbymakemodel?make=xxx&model=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

make

The make name (use niceName value)

 Yes
model

The model name (use niceName value)

 Yes

Method: findnewandusedmodelyearsbymakeidandyear

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findnewandusedmodelyearsbymakeidandyear?makeid=xxx&year=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

makeid

The make ID

 Yes
year

The year of interest

Method: findnewmodelyearsbymodelid

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findnewmodelyearsbymodelid?modelId=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

modelId

The model ID

 Yes

Method: findusedmodelyearsbymodelid

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findusedmodelyearsbymodelid?modelId=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

modelId

The model ID

 Yes

Method: findyearsbycategoryandpublicationstate

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/findyearsbycategoryandpublicationstate?category=xxx&state=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

category

The vehicle category (e.g. sedan, suv, ...etc)

 Yes
state

The publication state (e.g. new, used, future)

Method: formodelid

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/formodelid?modelid=xxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

modelid

The model ID

 Yes

Method: foryearmakemodel

URL

http://api.edmunds.com/{version}/api/vehicle/modelyearrepository/foryearmakemodel?make=xxx&model=xxx&year=xxxx&api_key=xxxxxxxxxx&fmt=json

Parameters

Name and Description Required?

make

The make name (use niceName value)

 Yes
model

The model name (use niceName value)

 Yes
year

The year of interest

 Yes

version 39 as of 2 years ago by Ismail Elshareef

5 Comments

  1. CieStudiosDev – 1 year ago

    Do you only support years 1990-2013?

  2. Troop – 7 months ago

    I have two quick questions:

    1) What are the exact values I can query for publication states? eg. New, NEW, used, USED...etc Reason I ask....it seems my queries only work when state is set to NEW. Everything else returns a gateway timeout.

    2) When using the Method: findyearsbycategoryandpublicationstate The response I'm receiving contains more info than just the years. I was hoping to a return similar to the Method finddistinctyearwithnew? where it only returned years.

    Great API.... and look forward to using it.

  3. Troop – 7 months ago

    Disregard my last comment. I've figured out a way around to get what I needed. Great stuff.

  4. Harivnder – 1 month ago

    what is the procedure to add vehicles in your Repository?

  5. Ismail Elshareef – 1 month ago

    Hi Harivnder,

    What do you mean exactly? You want to enter a vehicle that doesn't currently exist in our system? What's that vehicle?

    We don't have a process for writing data into our system using a public API at this time, but if you have a dataset that you feel should be in our database, by all means, please send it to us at api [at] edmunds.com

    Thanks, Ismail

Please sign in to post a comment.