# Reference lists

> Every closed vocabulary the API uses — locales, currencies, print regions, conditions, printings, graders, price variants and bases, change kinds, image faces and sizes — in one response.

- **Endpoint**: `GET /v1/reference`
- **Cost**: free, no key needed, cached for a day
- **Minimum plan**: free
- **Cache-Control**: `public, max-age=86400`

Source: https://pokemontcgapi.com/docs/api/reference/lists

One route, one object, no key: these are the values the schema accepts, so a filter built from them is never rejected as unsupported. Fetch it once at boot, not once per render — it is served with `public, max-age=86400`.

The printed vocabularies — rarity, supertype, energy types — are not lists here, because they are values read off each card, not enumerations of the schema. They are on every card object as `rarity`, `supertype` and `types`, and a query such as `q=rarity:"Double Rare"` matches them as printed.

## Headers

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `If-None-Match` | string | — | Send back the `ETag` you stored. The API returns a strong ETag on every catalogue response, and a 304 is a header exchange: no body, no database row read. |

## Example request

**curl**

```bash
curl -s "https://api.pokemontcgapi.com/v1/reference" \
  -H "X-Api-Key: $PTCG_API_KEY"
```

**TypeScript**

`request.ts`

```ts
const url = new URL("https://api.pokemontcgapi.com/v1/reference");

const res = await fetch(url, {
  headers: { "X-Api-Key": process.env.PTCG_API_KEY ?? "" },
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}

const { data, meta } = await res.json();
```

**Python**

`request.py`

```python
import os, httpx

res = httpx.get(
    "https://api.pokemontcgapi.com/v1/reference",
    headers={"X-Api-Key": os.environ["PTCG_API_KEY"]},
)
res.raise_for_status()
payload = res.json()
```

## Example response

`200 OK` · `Cache-Control: public, max-age=86400`

`response.json`

```json
{
  "data": {
    "locales": [
      "en",
      "ja",
      "zh",
      "fr",
      "de",
      "es",
      "it",
      "pt",
      "ko"
    ],
    "currencies": [
      "EUR",
      "USD",
      "GBP",
      "JPY"
    ],
    "print_regions": [
      "WEST",
      "JP",
      "CN",
      "KR"
    ],
    "conditions": [
      "MINT",
      "NEAR_MINT",
      "EXCELLENT",
      "GOOD",
      "LIGHT_PLAYED",
      "PLAYED",
      "POOR"
    ],
    "printings": [
      "NORMAL",
      "HOLOFOIL",
      "REVERSE_HOLO",
      "FIRST_EDITION",
      "FIRST_EDITION_HOLOFOIL"
    ],
    "grading_companies": [
      "PSA",
      "BGS",
      "CGC",
      "SGC",
      "ACE",
      "TAG"
    ],
    "price_variants": [
      "LOW",
      "MARKET",
      "TREND",
      "AVG_1D",
      "AVG_7D",
      "AVG_30D",
      "MEDIAN_GRADED",
      "INDEX"
    ],
    "price_bases": [
      "SOLD",
      "ASKING",
      "GUIDE",
      "DERIVED"
    ],
    "change_kinds": [
      "CARD",
      "SET",
      "SEALED",
      "PRICE",
      "IMAGE"
    ],
    "image_faces": [
      "FRONT",
      "BACK",
      "ART",
      "LOGO",
      "SYMBOL"
    ],
    "image_sizes": [
      "SMALL",
      "NORMAL",
      "LARGE"
    ]
  }
}
```