Esta documentação está a ser retirada para docs.carsxe.com. Este site será descontinuado a 1 de outubro de 2026.
Ir para a nova documentaçãoPopulate Year, Make, Model, and Variant dropdown menus — one API call returns one layer so you build menus step by step.
Use this endpoint to power cascading dropdowns in your own UI. Each request returns exactly one list — years, makes, models, variants (combined model + trim display strings, e.g. "Tacoma TRD Pro"), or trims (shorter manufacturer trim names when you explicitly request dimension=trims). Add year, make, and model filters to get better, more relevant results at each step.
Typical flow: start with no filters to list years → add year for makes → add make for models → add model for variants. One API call per dropdown level.
Bulk variant list: dimension=variants with year + make (no model) returns every variant for that make in one flat array.
Most requests cost 1 unit.
Exception: dimension=variants with year + make and no model costs 1 unit per model. The response includes modelCount, the number of distinct models, which is also the amount billed — with a minimum of 1 unit even when zero models match.
Example: 82 variant strings across 12 models → modelCount: 12 → 12 units.
Retrieve distinct values for Year, Make, Model, or Variant lists, filtered by the parameters you supply.
keyYour CarsXE API key.
dimensionOne of years, makes, models, trims, or variants. When set, the response contains exactly that one array if the required filters for that dimension are present. When omitted, the response layer is inferred from year, make, and model — see the table below.
yearFilter to a specific manufacturing year. Required when you filter by model without make.
makeFilter to a specific manufacturer (e.g., Toyota, Ford, Lexus). Required for dimension=models.
modelFilter to a specific model (e.g., Camry, F-150, LX). Required for dimension=trims and for dimension=variants unless both year and make are set. Also required for inferred variants when make is omitted.
trimOptional substring filter on trim names. Only applied when querying dimension=trims or dimension=variants (ignored for years, makes, and models).
dimension given)Omit dimension and the API returns one array inferred from your filters:
make? | model? | year? | Returns |
|---|---|---|---|
| — | — | — | years |
| — | — | ✓ | makes |
| ✓ | — | * | models |
| ✓ | ✓ | * | variants |
| — | ✓ | — | 400 — year required when model is given without make |
| — | ✓ | ✓ | variants if that model name maps to one make that year; 400 — add make if the name appears under multiple makes (e.g. Sentra) |
The API never returns more than one layer per response. To populate both a model list and a variant list, make two calls.
dimension valuesYou can also set dimension directly. trims and variants share most filter rules; variants also accepts year + make (no model) for a bulk list. variants returns friendly display strings ("Tacoma TRD Pro"), while trims returns shorter manufacturer trim names.
dimension | Typical use | Required filters |
|---|---|---|
years | List years (optionally for a known make + model) | — |
makes | List makes (optionally for a known year) | — |
models | List models for a make | make |
trims | Shorter manufacturer trim names for a vehicle | model (+ year when make omitted; + make when model is ambiguous) |
variants | Model + trim display strings for menus | year + make for a bulk list, or model (+ year when make omitted; + make when model is ambiguous) |
If you request dimension=variants or dimension=trims with only make (no year), the API returns models for that make with a message explaining that model is needed next — it does not error. With dimension=variants, year, and make, you get all variants for that make/year in one response.
successIndicates whether the request was successful.
inputEchoes back only the query parameters you submitted.
messageOptional guidance when the returned layer differs from the requested dimension, or when explaining what to add next for better results.
years / makes / modelsDistinct values for that layer when applicable.
variantsCombined model + trim display strings, deduplicated.
trimsShorter manufacturer trim names — only when dimension=trims with sufficient filters.
modelCountPresent only for bulk variants (dimension=variants + year + make, no model). Equals the number of distinct models, which is also the amount billed — except a zero-match query, which returns modelCount: 0 but still bills a minimum of 1 unit.
# Step 1 — list years (no filters)
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY
# Step 2 — makes for a year
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d year=2026
# Step 3 — models for a make
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d make=Toyota
# Step 4 — variants for year + make + model
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d year=2026 \
-d make=Toyota \
-d model=Tacoma
# Variants when you only know year + model (works when the name is unique to one make)
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d year=2026 \
-d model=Tacoma
# All variants for a make+year in one call (billed per model — see modelCount)
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d dimension=variants \
-d year=2025 \
-d make=Lexus
# Explicit dimension=variants with make only (no year) — returns models + guidance message
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d dimension=variants \
-d make=Toyota
# Reversed lookup — which years a make + model were sold
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d dimension=years \
-d make=Lexus \
-d model=TX
# Trim names for year + make + model (requires model — no bulk path for trims)
curl -G https://api.carsxe.com/v1/ymm-options \
-d key=CARSXE_API_KEY \
-d dimension=trims \
-d year=2026 \
-d make=Toyota \
-d model=Tacoma{
"success": true,
"input": { "year": 2026, "make": "Toyota", "model": "Tacoma" },
"variants": [
"Tacoma Limited",
"Tacoma SR",
"Tacoma SR5",
"Tacoma TRD Off-Road",
"Tacoma TRD PreRunner",
"Tacoma TRD Pro",
"Tacoma TRD Sport",
"Tacoma Trailhunter"
]
}{
"success": true,
"input": { "make": "Toyota" },
"models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"]
}{
"success": true,
"input": { "dimension": "variants", "year": 2025, "make": "Lexus" },
"variants": [
"ES 250",
"ES 300h",
"GX 550 Premium",
"IS 300",
"LC 500",
"LS 500",
"LX 600 Premium",
"NX 350",
"RC 350",
"RX 350",
"RZ 450e",
"TX 350",
"UX 300h"
],
"modelCount": 12
}{
"success": true,
"input": { "dimension": "variants", "make": "Toyota" },
"message": "To receive variants, include a model filter with this make. Models are returned instead.",
"models": ["4Runner", "Camry", "Corolla", "Tacoma", "Tundra"]
}