countries-api

name

countries-api

description

Query the free countries.dev REST API (no API key needed) for country data (names, capitals, populations, currencies, languages, flags, borders, timezones), city/place search and reverse geocoding, postal/ZIP code lookup, IP geolocation, and distance between locations. Use this skill whenever the user asks about countries, capitals, country codes (ISO alpha-2/alpha-3), currencies by country, national flags, neighbouring countries, city coordinates, "which country is this IP in", ZIP/postal code lookups, or distances between cities — even if they don't mention countries.dev or an API by name.

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

You need...	Use
One country, and you have its ISO code	/alpha/{code} (most reliable — prefer this)
One country by name	/name/{name} (substring match — may return several; pick the best match)
Lists filtered by region/currency/language/etc.	/region/…, /currency/…, /lang/…, etc.
Countries in a population or area range	/population?min=&max=, /area?min=&max=
A country's neighbours (full records)	/borders/{country name} — takes a name like germany, NOT an ISO code
City search / coordinates	/cities?q=… (ranked by population)
Any geographic feature (mountains, rivers…)	/places?q=…&class=…
Nearest city/place to coordinates	/cities/near?lat=&lng=, /places/near?lat=&lng=
ZIP/postal code → place + coordinates	/postal/{alpha2}/{code}
IP → country	/ip (caller), /ip/{ip}, or POST /ip for batches
Distance between two points	/distance?lat1=&lng1=&lat2=&lng2= or ?from=&to= (GeoNames IDs, not names)

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).