---
title: "YMM Options"
description: "Populate Year, Make, Model, and Variant dropdown menus — one API call returns one layer."
canonical_url: "https://docs.carsxe.com/docs/products/ymm-options"
markdown_url: "https://docs.carsxe.com/docs/products/ymm-options.md"
last_updated: "1980-01-01"
---

# YMM Options
URL: /docs/products/ymm-options
LLM index: /llms.txt
Description: Populate Year, Make, Model, and Variant dropdown menus — one API call returns one layer.

Task: Populate cascading Year/Make/Model/Variant dropdown menus with CarsXE.
Related: /docs/products/ymm-options, /docs/products/year-make-model, /docs/products/specifications

Use `/v1/ymm-options` 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`).

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.

Need full vehicle specs for a selected year, make, and model? Use [Year Make Model](/docs/products/year-make-model) (`/v1/ymm`) instead.

Endpoint: `/v1/ymm-options`

## Parameters

| Parameter | Required | Description |
|---|---|---|
| `key` | Yes | Your CarsXE API key |
| `dimension` | No | One of `years`, `makes`, `models`, `trims`, or `variants`. When set, the response contains exactly that array when the required filters are present. When omitted, the response layer is inferred from `year`, `make`, and `model`. |
| `year` | No | Filter to a specific manufacturing year. Required when filtering by `model` without `make`. |
| `make` | No | Filter to a manufacturer (e.g. `Toyota`, `Ford`, `Lexus`). Required for `dimension=models`. |
| `model` | No | Filter to a model (e.g. `Camry`, `F-150`, `LX`). Required for `dimension=trims` and for `dimension=variants` unless both `year` and `make` are set (bulk variant list). |

### Automatic response shape (no `dimension`)

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** if ambiguous (add `make`) |

The API never returns more than one layer per response. To populate both a model list and a variant list, make two calls.

### Bulk variant list

Set `dimension=variants` with `year` + `make` (no `model`) to fetch every variant for that make in one flat array — useful for client-side search or filter UIs. This path bills **one lookup unit per distinct model** in the result (e.g. 82 Lexus variant strings across 12 models = 12 billed units).

## Example

<CodeGroup title="Populate a cascading dropdown" tag="GET" label="/v1/ymm-options">

```bash
# Step 1 — list years (no filters)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY

# Step 2 — makes for a year
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026

# Step 3 — models for a make
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d make=Toyota

# Step 4 — variants for year + make + model
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d year=2026 \
  -d make=Toyota \
  -d model=Tacoma

# Bulk variants for a make + year (bills per distinct model)
curl -G https://api.carsxe.com/v1/ymm-options \
  -d key=YOUR_API_KEY \
  -d dimension=variants \
  -d year=2025 \
  -d make=Lexus
```

```js
const apiKey = "YOUR_API_KEY";

async function fetchYmmOptions(params) {
  const query = new URLSearchParams({ key: apiKey, ...params });
  const response = await fetch(
    `https://api.carsxe.com/v1/ymm-options?${query.toString()}`,
  );
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

const years = await fetchYmmOptions({});
const makes = await fetchYmmOptions({ year: "2026" });
const models = await fetchYmmOptions({ make: "Toyota" });
const variants = await fetchYmmOptions({
  year: "2026",
  make: "Toyota",
  model: "Tacoma",
});

console.log({ years, makes, models, variants });
```

```python
import httpx

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.carsxe.com/v1/ymm-options"

def fetch_ymm_options(**params):
    response = httpx.get(BASE_URL, params={"key": API_KEY, **params}, timeout=30.0)
    response.raise_for_status()
    return response.json()

years = fetch_ymm_options()
makes = fetch_ymm_options(year="2026")
models = fetch_ymm_options(make="Toyota")
variants = fetch_ymm_options(year="2026", make="Toyota", model="Tacoma")

print({"years": years, "makes": makes, "models": models, "variants": variants})
```

```bash {{ title: "Response — year=2026&make=Toyota&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"
  ]
}
```

```bash {{ title: "Response — dimension=variants&make=Toyota (fallback)" }}
{
  "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"]
}
```

</CodeGroup>

## Response

### Top-level shape

<YmmOptionsTopLevelShape />

Click `input` or a returned array to expand sample values. For the full interactive reference, try it live in the [API Reference](/api-reference/year-make-model/year-make-model-options).

Each successful response includes `success: true` and exactly **one** of `years`, `makes`, `models`, `trims`, or `variants`. The `message` field is optional guidance when the returned layer differs from what you requested.

<Properties>
  <Property name="success" type="boolean">
    `true` on a successful lookup.
  </Property>
  <Property name="input" type="object">
    Echoes back only the query parameters you submitted.
  </Property>
  <Property name="message" type="string">
    Optional guidance when the returned layer differs from the requested `dimension`, or when explaining what to add next for better results.
  </Property>
  <Property name="years / makes / models / trims / variants" type="array">
    Distinct values for the requested (or inferred) layer. Only one array is present per response.
  </Property>
</Properties>

### variants vs trims

`variants` returns display-ready strings like `"Tacoma TRD Pro"`. `trims` returns shorter manufacturer trim names. Both need a `model` (or disambiguating `year`/`make`) for single-vehicle lookups; only `dimension=variants` accepts `year` + `make` without `model` for a bulk list. For dropdown menus, use inferred responses or `dimension=variants`.

<Note>
  Every request requires a valid, active CarsXE API key and counts toward your **Year Make Model Options** quota — a separate bucket from [Year Make Model](/docs/products/year-make-model).
</Note>

## Errors

| Status | When it happens |
|---|---|
| `400` | Invalid `dimension`, missing required filters, or ambiguous `model` without `make` |
| `401` | Missing or invalid API key |
| `429` | Usage limit exceeded |
| `500` | Could not fetch data |

See the [Errors guide](/docs/guides/errors) for general error handling guidance.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).