Response format

Every endpoint returns JSON with standard HTTP status codes. List endpoints accept a handful of query parameters so you only fetch — and ship — what you need.

Lean by default

Country responses are lean by default — they omit a few bulky, rarely-needed fields (translations, altSpellings, maps, regionalBlocs) so the common case stays small. Everything else (capital, currencies, languages, timezones, borders, flag, ISO codes…) is always included.

When you do want the complete record, add full=true:

curl "https://countries.dev/alpha/US?full=true"

Or name the extra fields you need explicitly with fields (below) — fields always wins over the lean default, so you can request even the omitted ones.

Select fields

Use fields with a comma-separated list to return only the top-level properties you care about. Smaller payloads mean faster apps:

curl "https://countries.dev/countries?fields=name,capital,flag"

[
  { "name": "Afghanistan", "capital": "Kabul", "flag": "https://countries.dev/flags/af.svg" },
  { "name": "Albania", "capital": "Tirana", "flag": "https://countries.dev/flags/al.svg" }
]

fields works on both single-country and list endpoints.

Sort

sort chooses the property to order by; order is asc (default) or desc:

curl "https://countries.dev/countries?sort=population&order=desc&fields=name,population"

Paginate

limit caps the number of results and offset skips ahead — handy for tables and infinite scroll:

curl "https://countries.dev/countries?limit=10&offset=20"

Combine them

The parameters stack, so you can ask a precise question in one request — for example, the five largest countries by area:

curl "https://countries.dev/countries?sort=area&order=desc&limit=5&fields=name,area"