# BCP 47 Language Tags API
> IETF BCP 47 language tags (locales) as an API, built on the IANA Language Subtag Registry — 9,200+ subtags (languages, scripts, regions, variants, extlangs and grandfathered tags). The headline /parse endpoint validates and decomposes any language tag (e.g. zh-Hant-TW → Chinese + Han Traditional script + Taiwan; en-Latn-US, de-CH-1996, i-klingon) into its labelled subtags, flags invalid or deprecated parts, and recognises pre-registered redundant/grandfathered tags. Look up an individual subtag (de → German, Hant → Han Traditional, 419 → Latin America), or search the registry by description. Ideal for internationalization (i18n), locale validation, content negotiation and language-aware apps.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/bcp47-api/..."
```

## Pricing
- **Free** (Free) — 10,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 90,000 calls/Mo, 8 req/s
- **Pro** ($11/Mo) — 450,000 calls/Mo, 20 req/s
- **Mega** ($28/Mo) — 2,200,000 calls/Mo, 50 req/s

## Endpoints

### BCP 47

#### `GET /v1/parse` — Validate & decompose a BCP 47 language tag

**Parameters:**
- `tag` (query, required, string) — Language tag, e.g. zh-Hant-TW or en-Latn-US Example: `zh-Hant-TW`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bcp47-api/v1/parse?tag=zh-Hant-TW"
```

**Response:**
```json
{
    "data": {
        "tag": "zh-Hant-TW",
        "type": "redundant",
        "valid": true,
        "deprecated": null,
        "descriptions": [
            "Taiwan Chinese in traditional script"
        ],
        "preferred_value": null
    },
    "meta": {
        "timestamp": "2026-05-31T04:30:15.714Z",
        "request_id": "8aa4eb7c-d01c-4f4b-87d3-dcb5a1a15b46"
    },
    "status": "ok",
    "message": "Tag parsed",
    "success": true
}
```

#### `GET /v1/search` — Search subtags by description

**Parameters:**
- `q` (query, required, string) — Description search, e.g. chinese Example: `chinese`
- `type` (query, optional, string) — Restrict to a subtag type
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bcp47-api/v1/search?q=chinese&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "type": null,
        "count": 20,
        "limit": 20,
        "query": "chinese",
        "total": 60,
        "offset": 0,
        "results": [
            {
                "type": "language",
                "subtag": "zh",
                "description": "Chinese"
            },
            {
                "type": "language",
                "subtag": "ace",
                "description": "Achinese"
            },
            {
                "type": "language",
                "subtag": "cdo",
                "description": "Min Dong Chinese"
            },
            {
                "type": "language",
                "subtag": "cjy",
                "description": "Jinyu Chinese"
            },
            {
                "type": "language",
                "subtag": "cmn",
                "description": "Mandarin Chinese"
            },
            {
                "type": "language",
                "subtag": "cnp",
                "description": "Northern Ping Chinese"
            },
            {
                "type": "language",
                "subtag": "cpi",
                "description": "Chinese Pidgin English"
            },
            {
                "type": "language",
                "subtag": "cpx",
                "description": "Pu-Xian Chinese"
            },
            {
                "type": "language",
                "subtag": "csl",
                "description": "Chinese Sign Language"
            },
   
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/subtag` — Look up a single subtag

**Parameters:**
- `subtag` (query, required, string) — Subtag, e.g. de, Hant, US or 419 Example: `de`
- `type` (query, optional, string) — language | script | region | variant | extlang

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bcp47-api/v1/subtag?subtag=de"
```

**Response:**
```json
{
    "data": {
        "subtag": "de",
        "matches": 2,
        "records": [
            {
                "type": "language",
                "added": "2005-10-16",
                "subtag": "de",
                "descriptions": [
                    "German"
                ],
                "suppress_script": "Latn"
            },
            {
                "type": "region",
                "added": "2005-10-16",
                "subtag": "DE",
                "descriptions": [
                    "Germany"
                ]
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T04:30:15.856Z",
        "request_id": "e49f03e4-7261-4ea2-9838-a70532ffa006"
    },
    "status": "ok",
    "message": "Subtag retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Registry date, totals & type breakdown

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bcp47-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "/v1/parse validates & decomposes a full language tag (e.g. zh-Hant-TW). Types: language, extlang, script, region, variant, grandfathered, redundant.",
        "total": 9295,
        "types": [
            {
                "type": "language",
                "count": 8275
            },
            {
                "type": "region",
                "count": 305
            },
            {
                "type": "extlang",
                "count": 258
            },
            {
                "type": "script",
                "count": 225
            },
            {
                "type": "variant",
                "count": 139
            },
            {
                "type": "redundant",
                "count": 67
            },
            {
                "type": "grandfathered",
                "count": 26
            }
        ],
        "fields": [
            "type",
            "subtag",
            "descriptions",
            "added",
            "deprecated",
            "preferred_value",
            "suppress_script",
            "prefix",
            "scope",
            "macrolanguage"
        ],
        "source": "IANA Language Subtag Registry (BCP 47)",
        "file_date": "2026-05-05"
    },
    "meta": {
        "timestamp": "2026-05-31T04:30:15.904Z",
        "request_id": "a7e2ff2d-4746-4feb-b9b6-257be06f3bca"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/bcp47-api
OpenAPI spec: https://www.oanor.com/api/bcp47-api/openapi.json