Response format
Every countries.dev endpoint returns JSON. Learn how to select fields, sort and paginate the country API response with the fields, sort, order, limit and offset query parameters.
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.
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"fields applies everywhere; sort, order, limit and offset apply to list endpoints (those that return an array).
Authentication
The countries.dev API needs no API key, token or signup. Learn how authentication works (it doesn't), and how to call the country data API directly from the browser with CORS.
Errors & status codes
countries.dev uses standard HTTP status codes. Learn what 200, 400, 404 and 429 mean, how errors are returned as JSON, and how to handle a missing country gracefully.