# countries_api

> Read-only countries JSON API (REST Countries–compatible routes) with build-time Wikidata enrichment, public holidays, resolve/normalize helpers, and a separate flag CDN.

## Base URLs

- API: https://api.reqi.dev
- Flag CDN: https://cdn.reqi.dev
- Human docs: https://docs.reqi.dev
- Interactive API: https://docs.reqi.dev/api
- OpenAPI 3.1: https://api.reqi.dev/openapi.json
- Machine-readable summary: https://api.reqi.dev/llms.txt
- Health (metadata, uptime, latencyMs, dataset/manifest checks): https://api.reqi.dev/health
- Changelog (release notes): https://api.reqi.dev/changelog.txt

## API (v1)

Most endpoints return JSON arrays of country objects. GET /v1/countries/current, GET /v1/countries/resolve, and GET /v1/countries/normalize return a single object. Use `?fields=a,b,c` to project fields (supports dot paths, e.g. `name.common,cca2,flags` or `wikidataId,enrichment.government,holidays`).

Enriched fields (when present): top-level `wikidataId`, `unRegionalGroup`, nested `enrichment` (`fetchedAt`, `population` provenance, `economics`, `development`, `government`, `company` — largest Wikidata-reported revenue with HQ in country, often null — and `computed`), and `holidays` (Nager.Date, build-time). Full objects are large; prefer field projection.

List and filter responses return at most 25 countries per request (default `limit=5`). Batch and comma-separated alpha lookups accept up to 25 codes per request.

Pagination for GET /v1/countries and GET /v1/countries/list:

- `?page=<number>` — zero-based page in default country order (page 0 = first slice).
- `?page=randomized` — up to `limit` random countries (not paginated through the full set).
- `?page=random` — full list in a stable random order, `limit` countries per slice. Use `?index=0,1,…` with the same `?seed=` (response header `X-List-Seed` when omitted) until all countries are covered. Headers: `X-List-Seed`, `X-List-Index`, `X-List-Pages`.
- Without `page`, use `?offset=0` (default) and `?limit=1`–`25` (default 5).

Use `fields=*` for all fields. No bulk “all” endpoint.

### Agent recipes (copy-paste)

Form autofill (ISO, currency, calling codes, flags):

curl "https://api.reqi.dev/v1/countries/resolve?q=netherlands&fields=cca2,cca3,currencies,idd,flags"

Strict code normalization (UK → GB):

curl "https://api.reqi.dev/v1/countries/normalize?q=uk"

Canonical resolve with alias (Holland → NL):

curl "https://api.reqi.dev/v1/countries/resolve?q=holland"

Batch countries (ordered, max 25 codes):

curl "https://api.reqi.dev/v1/countries/batch?codes=nl,be,de&fields=name.common,cca2,flags"

Batch via alpha path (same ordering rules):

curl "https://api.reqi.dev/v1/countries/alpha/nl,be,de?fields=cca2,name.common"

Economics / development snapshot:

curl "https://api.reqi.dev/v1/countries/alpha/nl?fields=wikidataId,enrichment.economics,enrichment.development,enrichment.computed"

Government + Wikidata id:

curl "https://api.reqi.dev/v1/countries/alpha/us?fields=cca2,wikidataId,enrichment.government"

Euro-area list (paginate with offset):

curl "https://api.reqi.dev/v1/countries/currency/eur?fields=name.common,cca2,flags&limit=25&offset=0"

Public holidays (dedicated route):

curl "https://api.reqi.dev/v1/countries/holidays/nl?year=2026"

Public holidays on country record:

curl "https://api.reqi.dev/v1/countries/alpha/nl?fields=cca2,holidays"

Do not use GET /v1/countries/current in automated agents unless the user asked for “my location”; edge geo is often missing in cloud VMs.

### Routes

- GET /v1/countries — list countries
- GET /v1/countries/list — same as GET /v1/countries
- GET /v1/countries/random — one random country
- GET /v1/countries/resolve?q= — canonical resolve (aliases, ISO, names); optional `fields=` adds `country` projection; 404 may include `suggestions`
- GET /v1/countries/normalize?q= — strict ISO / alias normalization (no fuzzy names)
- GET /v1/countries/batch?codes= — batch lookup (ordered, max 25 codes)
- GET /v1/countries/holidays/{code} — public holidays; optional `?year=YYYY`
- GET /v1/countries/current — country for the request IP (single object; header X-Request-Country)
- GET /v1/countries/alpha/{codes} — by ISO 3166-1 alpha-2/3 (or ccn3) codes, comma-separated (max 25, ordered)
- GET /v1/countries/name/{name} — search by country name; `?fullText=true` for full-text match
- GET /v1/countries/capital/{capital} — by capital city
- GET /v1/countries/region/{region} — by region
- GET /v1/countries/subregion/{subregion} — by subregion
- GET /v1/countries/lang/{lang} — by language ISO 639 code
- GET /v1/countries/currency/{currency} — by ISO 4217 currency code
- GET /v1/countries/independent?status=true|false — filter by independent status
- GET /v1/countries/landlocked?status=true|false — landlocked countries
- GET /v1/countries/un-member?status=true|false — UN membership
- GET /v1/countries/callingcode/{code} — international dialing code (digits only)
- GET /v1/countries/calling-code/{code} — same filter; digits or leading +
- GET /v1/countries/demonym/{name} — demonym substring search
- GET /v1/countries/translation/{term} — translated name substring search
- GET /v1/countries/continent/{continent} — by continent
- GET /v1/countries/border/{code} — countries sharing a land border with {code} (excludes anchor)
- GET /v1/countries/cioc/{code} — Olympic committee code
- GET /v1/countries/fifa/{code} — FIFA code
- GET /v1/countries/tld/{tld} — top-level domain
- GET /v1/countries/stats — aggregate dataset counts (not paginated)
- GET /v1/borders/{code} — neighbors listed on anchor country borders[]
- GET /v1/status/{status} — ISO assignment status (e.g. officially-assigned)
- GET /v1/un-group/{group} — UN regional group
- GET /v1/government/{type} — substring on enrichment.government.type
- GET /v1/rank/{metric}?order=asc|desc — sorted countries (see /v1/meta/rank-metrics)
- GET /v1/meta — discovery index (catalogs, filters, utilities)
- GET /v1/meta/currencies|languages|regions|subregions|government-types|tlds|calling-codes|un-groups|statuses — paginated catalogs (?offset=0&limit=25, max 100)
- GET /v1/meta/rank-metrics — ranking metrics with coverage counts
- GET /v1/util/uuid — UUID v4 (utility)
- GET /v1/util/now?timezone=UTC — ISO/unix/local time
- GET /v1/util/hash?text=...&algorithm=sha256 — hex digest
- GET /v1/util/random?min=0&max=100 — random integer
- GET /v1/util/echo — echo query and safe headers
- GET /notice — production baseline JSON: versions (current/supported/deprecated/retired summaries), products, routes (excludes unreleased routes)

404 when no matches; 400 for invalid query params where applicable.

Meta catalog responses use kind + schemaVersion + total/offset/limit + items (not country projection). Utility responses use kind util-* JSON objects.

## Flags

Country records include `flags.svg` and `flags.png` URLs pointing at ISO code paths on the CDN (`/flags/{code}.svg` and `/flags/{code}.png`).

API host (`/v1/flags`):

- GET /flags/* on the API host is not available (404)
- GET /v1/flags/get/{code} — 301 redirect to https://cdn.reqi.dev/flags/{code}.png
- GET /v1/flags/get/png/{code} — 301 redirect to https://cdn.reqi.dev/flags/{code}.png
- GET /v1/flags/get/svg/{code} — 301 redirect to https://cdn.reqi.dev/flags/{code}.svg
- Add `?opaque=true` (or `?anonymous=true`) on any /v1/flags/get route for a 301 to content-hashed immutable filenames on the CDN

CDN host (cdn.reqi.dev):

- GET /flags/{code}.svg|png — serve flag bytes (default public URL)
- GET /get/{code} — 301 redirect to /flags/{code}.png (optional `?opaque=true` for hashed PNG)
- GET /get/png/{code} — 301 redirect to /flags/{code}.png
- GET /get/svg/{code} — 301 redirect to /flags/{code}.svg

Follow redirects with `-L` when downloading.

## Planned products

- /v1/boundaries — admin boundaries (not shipped)
- /v1/weather — weather data (not shipped)

## Examples

curl "https://api.reqi.dev/v1/countries?fields=name,cca2,population,currencies,flags"
curl "https://api.reqi.dev/v1/countries/alpha/nl?fields=wikidataId,unRegionalGroup,enrichment.government,enrichment.computed"
curl "https://api.reqi.dev/v1/countries?offset=5&limit=25&fields=name,cca2"
curl "https://api.reqi.dev/v1/countries/alpha/us"
curl "https://api.reqi.dev/v1/countries/currency/eur"
curl "https://api.reqi.dev/v1/countries/callingcode/31?fields=cca2,name"
curl "https://api.reqi.dev/v1/meta"
curl "https://api.reqi.dev/v1/rank/population?limit=5&fields=cca2,name,population"
curl "https://api.reqi.dev/v1/countries/stats"
curl "https://api.reqi.dev/v1/util/uuid"
curl -L "https://cdn.reqi.dev/get/nl" -o nl.png

## Data

Country core data from mledoze/countries. Build-time enrichment adds wikidataId, population (provenance in enrichment.population), HDI from UNDP HDR (provenance in enrichment.hdi; same value in enrichment.development.hdi), capital population, economics (gdpPerCapita derived from GDP ÷ population when Wikidata has no per-capita figure), development (life expectancy and Gini from Wikidata), government, optional company (largest reported revenue with HQ in country), and computed fields. Top-level unRegionalGroup uses a maintained ISO3 map. Public holidays from Nager.Date (`npm run data:holidays`). Aliases for resolve/normalize in data/country-aliases.json. Default country list projection is slim (name, cca2, cca3, flags); use fields=* or explicit fields for enrichment. Flag SVGs from flag-icons (MIT).

## License

MIT (API code). See repository for data and flag asset licenses.

## Documentation (plain text)

- Introduction: https://api.reqi.dev/docs.txt
- Quickstart: https://api.reqi.dev/docs/quickstart.txt
- Base URLs: https://api.reqi.dev/docs/base-url.txt
- Pagination: https://api.reqi.dev/docs/pagination.txt
- Field projection: https://api.reqi.dev/docs/fields.txt
- Errors: https://api.reqi.dev/docs/errors.txt
- Caching and headers: https://api.reqi.dev/docs/caching-and-headers.txt
- Endpoints overview: https://api.reqi.dev/docs/endpoints.txt
- Filter routes: https://api.reqi.dev/docs/filters.txt
- Discovery (GET /v1/meta): https://api.reqi.dev/docs/meta.txt
- OpenAPI: https://api.reqi.dev/docs/api.txt
- Country object: https://api.reqi.dev/docs/schema.txt
- Flag CDN: https://api.reqi.dev/docs/flags.txt
- LLMs: https://api.reqi.dev/docs/llms.txt
- Sources and licenses: https://api.reqi.dev/docs/data.txt