Countries API

countries.dev API

A free, no-auth REST API for country, city, postal-code, and IP-geolocation data. Base URL: https://countries.dev

• No API key, no signup, no documented rate limits. Just send GET requests.
• All responses are JSON (errors like "Country not found" come back as plain text with a 404 status — always check the HTTP status code).
• CORS is enabled, so it works from browsers as well as curl/server code.
• Data sources: country data plus GeoNames (~34k cities, ~12M places, ~1.8M postal codes across ~121 countries).

Quick start

# One country by ISO code (alpha-2 or alpha-3, case-insensitive)
curl https://countries.dev/alpha/JP

# Search by name (substring match, returns an array)
curl "https://countries.dev/name/japan?fields=name,capital,population"

# All countries, top 10 by population
curl "https://countries.dev/countries?fields=name,population&sort=population&order=desc&limit=10"

# Find a city and its coordinates
curl "https://countries.dev/cities?q=taipei&limit=5"

# Geolocate an IP
curl https://countries.dev/ip/8.8.8.8

Choosing the right endpoint

For the complete endpoint list, every query parameter, response schemas, and verified examples, read references/endpoints.md.

Key conventions (learned from live testing — trust these)

1. Single-lookup endpoints return an object; search/filter endpoints return an array — even when only one item matches. /alpha/JP → object; /name/japan → [ {...} ].
2. Use fields= aggressively. Full country records are large. Request only what you need: ?fields=name,capital,population. Use ?fields=full to get everything including altSpellings, maps, translations, and regionalBlocs (these four are omitted by default).
3. List endpoints support sort, order (asc/desc), limit, offset for sorting and pagination.
4. Name search is substring-based: /name/united returns every country containing "united". Don't assume the first result is the intended one — match on the name field or fall back to /alpha/{code} when you know the code.
5. /borders takes a country name (/borders/germany works; /borders/DE and /borders/DEU return 404 "Country not found"). To get just neighbour codes, read the borders array (alpha-3 codes) from the country record instead.
6. /distance does not accept city names or country codes — only lat1/lng1/lat2/lng2 coordinates or GeoNames IDs via from/to. To get the distance between two named cities, first resolve each via /cities?q=name to get its geonameId, then call /distance?from=ID&to=ID.
7. URL-encode special characters: timezone lookups need the + encoded, e.g. /timezone/UTC%2B08:00.
8. Flags: the flag field is an emoji (🇹🇼); image URLs live in flags.png / flags.svg (hosted on flagcdn.com).