# Catalogue

The AutoUncle vehicle catalogue identifies vehicles as brand → model → generation → drivetrain, plus equipment variants per brand. Sending catalogue IDs in `vehicle.catalogue` removes ambiguity and raises precision. All catalogue calls are free, need `catalogue:read`, and share a rate limit of 120 requests per minute per workspace.

Human-readable reference: https://data-services.autouncle.com/docs/reference/catalogue

## IDs

- IDs are opaque strings with a prefix: `b-` brand, `cm-` model, `mg-` generation, `dv-` drivetrain, `ev-` equipment variant. Example: `dv-947a3199394a5a4b41cb2869`.
- Use them exactly as returned. Never parse, shorten or construct them.
- They are stable for a catalogue version. `GET /v1/catalogue/version` returns a string such as `5.6.7:NEW`; refresh cached IDs when it changes. An outdated ID returns `unknown_catalogue_id`.

## Walk the hierarchy

| Step | REST | MCP `search_vehicles` arguments | Returns |
| --- | --- | --- | --- |
| Find a starting point | `GET /v1/catalogue/search?q=golf` | `{"kind":"search","query":"golf"}` | Up to 20 brands and 80 models whose names contain the text |
| Brands | `GET /v1/catalogue/brands` | `{"kind":"brands"}` | All brands (about 320) |
| Models of a brand | `GET /v1/catalogue/brands/{brand_id}/models` | `{"kind":"models","parent_id":"b-..."}` | Models with `brand_id` |
| Generations of a model | `GET /v1/catalogue/models/{model_id}/generations?year=2021` | `{"kind":"generations","parent_id":"cm-...","year":2021}` | Generations with `from_year`, `to_year`, optional `body` |
| Drivetrains of a generation | `GET /v1/catalogue/generations/{generation_id}/drivetrains?fuel=petrol&transmission=manual` | `{"kind":"drivetrains","parent_id":"mg-..."}` (no filters over MCP) | Drivetrains with `fuel`, `power_hp`, `transmission`, `engine_size_l`, `battery_kwh`, `drive`, `doors` |
| Equipment variants of a brand | `GET /v1/catalogue/brands/{brand_id}/equipment-variants` | `{"kind":"equipment-variants","parent_id":"b-..."}` | Trim and equipment lines |
| One item | `GET /v1/catalogue/{kind}/{id}` | not available | The item |

Lists are sorted by name and not paginated. Every list response has `object: "list"`, `version`, `data`, `notes` and `attributions`.

## Search tips

- Search is a case-insensitive substring match on catalogue names, including "brand model" names. It has no synonyms: the brand is `VW`, so `q=Volkswagen Golf` returns nothing, while `q=golf` or `q=vw golf` works.
- Queries need 2 to 200 characters.
- Search returns brands and models only. Continue with generations and drivetrains.

## Choosing the right entries

- **Generation:** pass `year` (registration year) to keep only generations whose production years include it. Several can remain, for example hatchback and estate (`Golf VIII` and `Golf VIII Variant`). Pick by body style; ask the user when unsure.
- **Drivetrain:** match fuel, transmission and power. Names follow the pattern `1.5 TSI (130 Hp)`, with `DSG`, `4MOTION` and similar suffixes.
- **Drivetrain value differences:** in catalogue results `drive` is a label such as `2WD` or `AWD`, and `fuel` can be a raw catalogue value such as `CNG_Hybrid`. In a valuation request, `vehicle.drive` takes `fwd`, `rwd`, `awd` or `4wd`, and `vehicle.fuel` takes the values from `/v1/catalogue/enums`. You do not need to send them when you send `drivetrain_id`.
- **Model aliases:** some models stand for a set of generations (for example a named variant). Their generations and drivetrains are returned as usual; a valuation resolves them to the canonical model.

## Using IDs in a valuation

```json
{
  "country": "DK",
  "vehicle": {
    "catalogue": { "drivetrain_id": "dv-947a3199394a5a4b41cb2869" },
    "model_year": 2021,
    "mileage": { "value": 45000, "unit": "km" }
  }
}
```

- Send the lowest level you know. Parents are derived (`source: catalogue_derived` in `identification.fields`). In a returned AVS vehicle, the `autouncle` entry of `identity.drivetrain.ids` is the same as `vehicle.catalogue.drivetrain_id`.
- If you send several levels, they must belong to one path, or the valuation is refused with `catalogue_id_conflict`. Do not also send `make`/`model` text that names a different vehicle.
- `equipment_variant_id` must belong to the same brand.

## Enums

`GET /v1/catalogue/enums` lists accepted values for `fuel`, `transmission`, `drive`, mileage units, `price_basis`, `resolution`, precision grades and the `equipment` feature keys (for example `INFOTAINMENT_NAVIGATION`, `CAMERA_PARKING_REAR`, `BATTERY_HEAT_PUMP`). Unrecognized equipment keys produce the `equipment_not_recognized` warning.

## Markets

`GET /v1/catalogue/countries` lists the market codes to send as `country`, each market's mileage unit and its `availability`: DK, SE (mil), DE, IT, ES, AT, PT, PL, FI, RO, GB (mi), FR, CH, NL are `general` (enabled for new workspaces); BE is `on_request` and returns `403 country_not_enabled` until AutoUncle enables it. Listing a market does not guarantee a live valuation model for it; check with a live request.