---
title: "Country lookup: ISO 3166 codes, currency, TLD, UN region and ISO 3166-2 subdivisions"
method: GET
path: "/v1/ref/country"
tags: ["deterministic", "no-api-key", "ref", "countries", "iso-3166"]
---

# Country lookup: ISO 3166 codes, currency, TLD, UN region and ISO 3166-2 subdivisions

`GET /v1/ref/country`

## Request

- Base URL: `https://api.duoleads.com`
- URL: `https://api.duoleads.com/v1/ref/country`
- Auth: none declared

Country lookup: find a country or territory by ISO 3166-1 alpha-2, alpha-3 or numeric code, or by name, and get the other codes, the official and common English names, the UN M49 region and sub-region, the currencies in use, the country-code TLD, and optionally the full ISO 3166-2 subdivision list with each subdivision's type. Also resolves an ISO 3166-2 subdivision code such as NL-NH directly. Names are matched case- and accent-insensitively.

**Output (`data`):** found, kind (country|subdivision), alpha_2, alpha_3, numeric, name, official_name (the ISO 3166-1 official name from Debian iso-codes, e.g. "Kingdom of the Netherlands"; the short name where ISO defines no separate official name; always a string), m49 {region, region_name, subregion, subregion_name, intermediate, intermediate_name} (UN M49 codes as zero-padded 3-character strings; subregion and intermediate are null where the hierarchy has no such level), currencies [ISO 4217 alpha-3, legal tender in use per CLDR], tld [".xx"] (the ccTLD in actual use, so GB gives .uk; empty where none is delegated), subdivision_count (always present: the number of ISO 3166-2 subdivisions), and with include=subdivisions subdivisions [{code, name, type, parent}] (ISO 3166-2 from Debian iso-codes main of 2026-09-28, source order; parent is the parent subdivision code or null; countries with none return an empty list). A code of the form CC-XXX (e.g. NL-NH) resolves a subdivision: kind is subdivision, subdivision {code, name, type, parent} is added, and the country fields describe its country. m49, currencies and tld are omitted when not named in include; subdivision_count is not. A name search adds matches [{alpha_2, alpha_3, numeric, name}] (exact name first, then substring; at most 25) plus total_matches, and the top-level fields describe the first match. ZZ and other non-ISO codes are never found.

Deterministic: identical input returns identical output, so the response is served with `Cache-Control: private, max-age=31536000, immutable` (the paying client may cache it indefinitely; shared caches must not, because the response is paid).

Sources: iso-codes Debian iso-codes data/iso_3166-1.json (official_name) and data/iso_3166-2.json, retrieved 2026-09-28 (published 2026-09-28, LGPL-2.1-or-later); country-codes datasets/country-codes, retrieved 2026-09-28 (published 2026-09-28, PDDL-1.0); cldr 48.2.2 (published 2026-09-28, Unicode-3.0). Echoed in `meta.sources`.

Price: $0.05 USDC per call (x402, Base). Route contract version 1.0.0. Docs: https://api.duoleads.com/docs#ref-country

## Query parameters

- `code` string
- `name` string
- `include` string

## Response `200`

Paid and settled. `data` is route-specific; a route that judges its input returns 200 with `data.valid: false` for a bad value.

- object
  - `ok` unknown, required
  - `route` '/v1/ref/country', required
  - `version` '1.0.0', required
  - `data` object, required: found, kind (country|subdivision), alpha_2, alpha_3, numeric, name, official_name (the ISO 3166-1 official name from Debian iso-codes, e.g. "Kingdom of the Netherlands"; the short name where ISO defines no separate official name; always a string), m49 {region, region_name, subregion, subregion_name, intermediate, intermediate_name} (UN M49 codes as zero-padded 3-character strings; subregion and intermediate are null where the hierarchy has no such level), currencies [ISO 4217 alpha-3, legal tender in use per CLDR], tld [".xx"] (the ccTLD in actual use, so GB gives .uk; empty where none is delegated), subdivision_count (always present: the number of ISO 3166-2 subdivisions), and with include=subdivisions subdivisions [{code, name, type, parent}] (ISO 3166-2 from Debian iso-codes main of 2026-09-28, source order; parent is the parent subdivision code or null; countries with none return an empty list). A code of the form CC-XXX (e.g. NL-NH) resolves a subdivision: kind is subdivision, subdivision {code, name, type, parent} is added, and the country fields describe its country. m49, currencies and tld are omitted when not named in include; subdivision_count is not. A name search adds matches [{alpha_2, alpha_3, numeric, name}] (exact name first, then substring; at most 25) plus total_matches, and the top-level fields describe the first match. ZZ and other non-ISO codes are never found.
    - `found` boolean, required
    - `kind` string
    - `alpha_2` string
    - `alpha_3` string
    - `numeric` string
    - `name` string
    - `official_name` string
    - `m49` object
      - `region` string, nullable, required
      - `region_name` string, nullable, required
      - `subregion` string, nullable, required
      - `subregion_name` string, nullable, required
      - `intermediate` string, nullable, required
      - `intermediate_name` string, nullable, required
    - `currencies` string[]
    - `tld` string[]
    - `subdivision_count` integer
    - `subdivision` object
      - `code` string, required
      - `name` string, required
      - `type` string, required
      - `parent` string, nullable, required
    - `subdivisions` object[]
      - `code` string, required
      - `name` string, required
      - `type` string, required
      - `parent` string, nullable, required
    - `matches` object[]
      - `alpha_2` string, required
      - `alpha_3` string, required
      - `numeric` string, required
      - `name` string, required
    - `total_matches` integer
  - `meta` Meta, required
    - `disclaimer` string, required: Legal short disclaimer, identical on every response.
    - `request_id` string, required: ULID.
    - `computed_at` string, date-time, required: RFC 3339 UTC with milliseconds.
    - `price_usd` string, required: Decimal string, "0.05".
    - `deterministic` boolean, required
    - `sources` object[]: Present only on routes that read a vendored dataset: the exact edition that answered.
      - `id` string, required
      - `version` string, required
      - `published` string, required
      - `attribution` string
      - `licence` string

## Other responses

- `400`: MISSING_PARAM, INVALID_PARAM or UNSUPPORTED_VALUE. Not charged: validation runs before the paywall.
- `402`: Payment required. No valid PAYMENT-SIGNATURE was supplied: read the base64 PAYMENT-REQUIRED header (or this body) for the price ($0.05 = 50000 atomic USDC on eip155:8453), sign an EIP-3009 authorization and retry. Also returned when settlement is declined (PAYMENT_FAILED). Nothing is charged on a 402.
- `404`: NOT_FOUND: unknown path. Not charged.
- `405`: METHOD_NOT_ALLOWED: only GET and HEAD are served. Not charged.
- `413`: INPUT_TOO_LARGE: a parameter exceeded its documented maximum length. Not charged.
- `500`: INTERNAL: a server bug. Not charged.

---

[API](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo.md) · [All operations](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/llms.txt) · [OpenAPI document](https://skmtc.dev/duoleads/apis/duo-data-utilities-iban-isin-vat-tax-id-barcode-timezone-geo/revisions/18790d59615e?raw)