# countries_api

> Read-only countries JSON API (REST Countries–compatible routes) with build-time Wikidata enrichment 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/current returns a single country object for the caller’s IP (edge geo). Use `?fields=a,b,c` to project fields (supports dot paths, e.g. `name.common,cca2,flags` or `wikidataId,enrichment.government,enrichment.computed`).

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

List responses return at most 5 countries per request. Use `?limit=1`–`5` (default 5).

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

- `?page=<number>` — zero-based page in default country order (page 0 = first 5).
- `?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` as before.

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

- GET /v1 — list countries
- GET /v1/list — same as GET /v1
- GET /v1/random — one random country
- GET /v1/current — country for the request IP (single object; header X-Request-Country)
- GET /v1/alpha/{codes} — by ISO 3166-1 alpha-2/3 (or ccn3) codes, comma-separated
- GET /v1/name/{name} — search by country name; `?fullText=true` for full-text match
- GET /v1/capital/{capital} — by capital city
- GET /v1/region/{region} — by region
- GET /v1/subregion/{subregion} — by subregion
- GET /v1/lang/{lang} — by language ISO 639 code
- GET /v1/currency/{currency} — by ISO 4217 currency code
- GET /v1/independent?status=true|false — filter by independent status
- GET /v1/notice — JSON summary of the production v1 and site surface (baseline; excludes unreleased routes)

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

## Flags (CDN)

Country records include `flags.svg` and `flags.png` URLs pointing at the CDN base. Opaque filenames hide ISO codes in static asset paths.

- GET /get/{code} — 301 redirect to default PNG (e.g. /get/nl)
- GET /get/png/{code} — 301 redirect to PNG
- GET /get/svg/{code} — 301 redirect to SVG

Legacy API host paths `/flags/get/...` also work. Follow redirects with `-L` when downloading.

## Examples

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

## Data

Country core data from mledoze/countries. Build-time Wikidata enrichment adds wikidataId, population (with provenance in enrichment.population), capital population, economics, development, government, optional company (largest reported revenue with HQ in country), and computed fields under enrichment. Top-level unRegionalGroup uses a maintained ISO3 map. Use fields= to project (e.g. wikidataId,unRegionalGroup,enrichment.government). 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
- GET /v1/current: https://api.reqi.dev/docs/current.txt
- GET /v1/notice: https://api.reqi.dev/docs/notice.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
- REST Countries compatibility: https://api.reqi.dev/docs/rest-countries.txt