Year Make Model includes two lightweight APIs for cases where you do not have a VIN. Use Year Make Model to find the best matching vehicle and trim from basic vehicle identity. Use the OBD-II code decoder to map diagnostic trouble codes to readable diagnosis text.
Year Make Model
Look up vehicle data by year, make, and model, with an optional trim hint. This is useful when a VIN is unavailable but you still need structured specs, colors, features, pricing, or trim options.
Endpoint: /v1/ymm
Parameters
| Parameter | Required | Description |
|---|---|---|
year | Yes | Vehicle model year, numeric, between 1900 and the current model year plus one |
make | Yes | Manufacturer, for example Toyota, Ford, or BMW |
model | Yes | Vehicle model, for example Camry, F-150, or X5 |
trim | No | Trim hint, for example XLE or Sport; fuzzy matched when possible |
allTrimOptions | No | Pass 1 to return all trim options for the year, make, and model |
Example
Look up by year, make, and model
Response
Top-level shape
Click any object or array to expand it and see sample data. For the full interactive reference, try it live in the API Reference.
All response fields are optional except success. Availability varies by vehicle, trim, and source coverage.
bestMatch
The bestMatch object contains the matched vehicle and trim data.
- Name
make- Type
- string
- Description
Vehicle manufacturer. Example:
"Toyota".
- Name
model- Type
- string
- Description
Vehicle model. Example:
"Camry".
- Name
year- Type
- string
- Description
Vehicle model year. Example:
"2023".
- Name
name- Type
- string
- Description
Full trim and body description for the matched vehicle. Example:
"XLE 4dr Sedan (3.5L 6cyl 8A)".
- Name
base_msrp- Type
- number
- Description
Original base manufacturer's suggested retail price when available.
- Name
base_invoice- Type
- number
- Description
Original base dealer invoice price when available.
- Name
total_seating- Type
- number
- Description
Factory seating capacity for the matched trim.
- Name
color- Type
- object
- Description
Available exterior and interior color options.
- Name
features- Type
- object
- Description
Grouped feature and specification data, usually under
standard.
trimOptions
When allTrimOptions=1 is passed, trimOptions returns available trims for the requested year, make, and model. Use this when users need to choose a trim before requesting the best match.
color
Color data is grouped by exterior and interior. Each item uses the same shape:
- Name
name- Type
- string
- Description
Manufacturer color or upholstery name. Example:
"Supersonic Red"or"Black, leather".
- Name
rgb- Type
- string
- Description
Comma-separated RGB value. Example:
"226,5,0".
features
Features are grouped into categories under features.standard.
- Name
category- Type
- string
- Description
Feature category name. Example:
"Power Feature","Warranty", or"Measurements".
- Name
features- Type
- array
- Description
List of feature items in this category.
Each feature item has:
- Name
name- Type
- string
- Description
Feature or measurement name. Example:
"hands-free entry"or"Rear leg room".
- Name
value- Type
- string | null
- Description
Value for the feature when the source provides one. Feature flags often return
null; measurements usually return a string such as"38.0 in.".
input
The input object echoes the request values used for the lookup. It can include year, make, model, trim, and allTrimOptions.
If trim is omitted, the API returns the best/default trim match for the year, make, and model. If trim is provided but not exact, the API attempts a close match. Pass allTrimOptions=1 when you need the available trims instead of a single best match. Response fields vary by vehicle and source availability.
OBD-II Code Decoder
Decode an OBD-II diagnostic trouble code into a readable diagnosis.
Endpoint: /obdcodesdecoder
Parameters
| Parameter | Required | Description |
|---|---|---|
code | Yes | OBD-II diagnostic trouble code, for example P0115 |
key | Yes | Your CarsXE API key |
format | No | json by default, or xml if supported by your endpoint configuration |
Example
Decode an OBD-II code
For the full interactive reference, try it live in the API Reference.
Response
- Name
success- Type
- boolean
- Description
Whether the code was decoded.
- Name
diagnosis- Type
- string
- Description
Diagnostic description for the trouble code.
- Name
date- Type
- string
- Description
Lookup timestamp or date returned by the API.
- Name
code- Type
- string
- Description
Normalized OBD code returned by the API.
Errors
See the Errors guide for the full list.
Common Year / Make / Model errors:
- 400 - Missing or invalid
year,make, ormodel. - 404 - No vehicle matched the specified year, make, and model.
- 500 - Could not fetch data.
Common OBD-II code decoder errors:
- 400 - Missing OBD code.
- 500 - Could not find the requested code.
Common errors for both endpoints:
- 401 - API key is missing, invalid, disabled, or unauthorized.
- 429 - Usage limit exceeded.