# countries_api

> Read-only countries JSON API (REST Countries–compatible routes) with Wikidata-enriched population fields and a separate flag CDN.

## Base URLs

- API: https://flags.robskan.nl
- Flag CDN: https://cdn.flags.robskan.nl
- Machine-readable summary: https://flags.robskan.nl/llms.txt
- JSON metadata: https://flags.robskan.nl/health

## API (v1)

All endpoints return JSON arrays of country objects unless noted. Use `?fields=a,b,c` to project fields (supports dot paths, e.g. `name.common,cca2,flags`).

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/alpha/{codes} — by ISO 3166-1 alpha-2/3 codes (semicolon-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

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://flags.robskan.nl/v1?fields=name,cca2,population,currencies,flags"
curl "https://flags.robskan.nl/v1?offset=5&limit=5&fields=name,cca2"
curl "https://flags.robskan.nl/v1/alpha/us"
curl "https://flags.robskan.nl/v1/currency/eur"
curl -L "https://cdn.flags.robskan.nl/get/nl" -o nl.png

## Data

Country core data from mledoze/countries; population and capital population enriched from Wikidata. Flag SVGs from flag-icons (MIT).

## License

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