Every country on Earth in one fast, enriched lookup
Countries API
The Countries API gives you a complete, normalized reference dataset for ~250 countries and territories behind a single, blazing-fast endpoint. Look up any country by ISO code (cca2, cca3, ccn3 or IOC/cioc), search by name with smart ranking, or filter the whole world by region, currency, language, or international dialing code.
Responses come back as clean JSON in milliseconds. There are no upstream third-party calls and no surprise rate limits because the entire dataset is bundled and served straight from Cloudflare's edge. Every country is enriched with ready-to-render flag image URLs (PNG + SVG) and a normalized array of full international calling codes.
Free tier included, no credit card required. One key works across all 49 APIs.
- Countries
- 250+
- Response Time
- <50ms
- Uptime SLA
- 99.9%
Key features
- Resolve a country by cca2, cca3, ccn3 or cioc code
- Ranked name search (exact > prefix > substring)
- Filter by region, currency, language or calling code
- Ready-to-use flag image URLs in PNG and SVG
- Normalized international calling_codes array
- Field projection via ?fields= to pull only what you render
- Bundled offline dataset, no upstream dependencies
Built for
- Country pickers and phone-number forms
- Checkout and address flows
- Rendering flags in dashboards and tables
- Localizing apps by region or language
- Currency and Eurozone lookups
- Mapping dialing codes to countries
- Data enrichment pipelines
- Geographic analytics and reporting
Try it
Build the request for your data
Edit the parameters below and see the exact curl command and JSON response you will get. No key required to preview.
Parameters
GET /countries/v1/code/AW?apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io
{
"country": {
"name_common": "Aruba",
"name_official": "Aruba",
"cca2": "AW",
"cca3": "ABW",
"ccn3": "533",
"cioc": "ARU",
"region": "Americas",
"subregion": "Caribbean",
"capital": ["Oranjestad"],
"currencies": { "AWG": { "name": "Aruban florin", "symbol": "ƒ" } },
"idd": { "root": "+2", "suffixes": ["97"] },
"languages": { "nld": "Dutch", "pap": "Papiamento" },
"latlng": [12.5, -69.97],
"area": 180,
"borders": [],
"tld": [".aw"],
"flag_emoji": "🇦🇼",
"demonyms": { "f": "Aruban", "m": "Aruban" },
"landlocked": false,
"independent": false,
"unMember": false,
"altSpellings": ["AW"],
"flag_png": "https://flagcdn.com/w320/aw.png",
"flag_svg": "https://flagcdn.com/aw.svg",
"calling_codes": ["+297"]
}
}Documentation
Countries API Documentation
The Countries API is a fast, offline-grade reference for ~250 countries and territories. Resolve a single country by ISO code (cca2/cca3/ccn3/cioc), search by name with ranked results, or filter the full dataset by region, currency, language or international calling code. Every country is enriched with flag image URLs (flag_png, flag_svg) and a normalized calling_codes array.
Base URL
https://api.apicodex.ioAuthentication
Authenticate by passing your API key as the ?apikey= query parameter on every request:
https://api.apicodex.io/countries/v1/code/AW?apikey=YOUR_KEYRequest and response
Illustrative values. Confirm current endpoint behavior, quotas, and data freshness in the API documentation before production use.
GET /countries/v1/code/AW?apikey=YOUR_KEY HTTP/1.1{
"country": {
"name_common": "Aruba",
"name_official": "Aruba",
"cca2": "AW",
"cca3": "ABW",
"ccn3": "533",
"cioc": "ARU",
"region": "Americas",
"subregion": "Caribbean",
"capital": ["Oranjestad"],
"currencies": { "AWG": { "name": "Aruban florin", "symbol": "ƒ" } },
"idd": { "root": "+2", "suffixes": ["97"] },
"languages": { "nld": "Dutch", "pap": "Papiamento" },
"latlng": [12.5, -69.97],
"area": 180,
"borders": [],
"tld": [".aw"],
"flag_emoji": "🇦🇼",
"demonyms": { "f": "Aruban", "m": "Aruban" },
"landlocked": false,
"independent": false,
"unMember": false,
"altSpellings": ["AW"],
"flag_png": "https://flagcdn.com/w320/aw.png",
"flag_svg": "https://flagcdn.com/aw.svg",
"calling_codes": ["+297"]
}
}Code examples
curl --request GET \
--url 'https://api.apicodex.io/countries/v1/code/AW?apikey=YOUR_KEY'Available Endpoints
GET /countries/v1/all
List every country (enriched). Optionally filter by region, project a subset of fields, and cap results with limit (default 300).
/countries/v1/all?region=Oceania&fields=name_common,cca2,calling_codes&apikey=YOUR_KEYGET /countries/v1/code/{code}
Resolve one country by cca2, cca3, ccn3 or cioc, tried in that order, case-insensitive.
/countries/v1/code/AW?apikey=YOUR_KEYGET /countries/v1/search
Partial, case-insensitive name search over name_common, name_official and altSpellings. Ranked exact > prefix > substring.
/countries/v1/search?name=united&apikey=YOUR_KEYGET /countries/v1/region/{region}
List countries in a region: Africa, Americas, Asia, Europe, Oceania or Antarctic (case-insensitive).
/countries/v1/region/Europe?apikey=YOUR_KEYGET /countries/v1/currency/{code}
List countries using an ISO 4217 currency code (case-insensitive).
/countries/v1/currency/EUR?apikey=YOUR_KEYGET /countries/v1/language/{code}
List countries with an ISO 639-3 language code (case-insensitive).
/countries/v1/language/eng?apikey=YOUR_KEYGET /countries/v1/calling-code/{code}
List countries by international calling code, with or without a leading '+'. Resolves shared roots (+1 -> US, CA) and specific codes (+297 -> Aruba).
/countries/v1/calling-code/1?apikey=YOUR_KEYQuery Parameters
Required parameters
apikeyYour API key, passed as a query parameter on every request.nameName substring to search for (required on /search).codePath value: ISO code, currency code, language code, or calling code depending on the endpoint.regionPath value on /region: Africa, Americas, Asia, Europe, Oceania or Antarctic.
Optional parameters
fieldsComma-separated field names to project, e.g. name_common,cca2,calling_codes (on /all).regionFilter /all results by region (case-insensitive).limitMax results, clamped 1..500. Default 300 for list endpoints, 50 for /search.
Pricing
Countries API Pricing
One key, one subscription, all 49 APIs. Start free and upgrade when you grow. No minimums, no lock-in.
This API costs 1 credit per request. Credits are shared across every API on your plan.
Estimate your monthly cost
Drag the slider to match your expected request volume. We will recommend the cheapest plan that covers it.
Recommended plan
Starter
$29.99 /month
Free
- All 49 APIs included
- No credit card required
- Full documentation and examples
Starter
Popular- All 49 APIs included
- Email support
- Usage dashboard and analytics
Pro
- All 49 APIs included
- Priority support
- Up to 5 API keys
Need a different plan?
Tell us about your API, volume, or support requirements.
Coming soon · MCP
Use the Countries API from your AI agent
The API Codex MCP server will expose this API, and the other 39, to Claude, Cursor and any MCP client as tools. Same key, same credits, one config entry.
FAQ
Frequently asked questions
Pass your API key as the apikey query parameter on every request, for example /countries/v1/code/AW?apikey=YOUR_KEY. If you prefer headers, send the same key as X-Api-Key instead. Create a free key at dash.apicodex.io.
The /countries/v1/code/{code} endpoint resolves a country by cca2 (two-letter, e.g. AW), cca3 (three-letter, e.g. ABW), ccn3 (numeric, e.g. 533) or cioc (IOC, e.g. ARU). It tries those formats in that order and matches case-insensitively, so you can pass user input directly. If no country matches, the API returns a 404 with an error message.
Every country object is enriched with two ready-to-use flag image URLs: flag_png (a 320px PNG hosted on flagcdn.com) and flag_svg (a scalable vector version). You can use these directly in an img tag without hosting any assets yourself. A flag_emoji field is also included for text-based rendering.
The calling_codes array contains clean, full international dialing codes such as ['+297']. North American Numbering Plan members like the US and Canada collapse to a single ['+1'] instead of listing hundreds of area codes, and code-less territories like Antarctica return an empty array. The /countries/v1/calling-code/{code} endpoint resolves both shared roots (+1 returns US and CA) and specific codes (+297 returns Aruba), with or without a leading plus.
Yes. The /countries/v1/all endpoint supports a ?fields= parameter that projects only the comma-separated fields you specify, for example name_common,cca2,flag_svg. All list endpoints also accept a ?limit= parameter clamped between 1 and 500 (default 300 for lists, 50 for search), so you can keep payloads small and fast for UI components like country pickers.
The entire ~250-country dataset is bundled and served from Cloudflare's edge, so lookups resolve locally without any upstream third-party calls. That delivers predictable single-digit to low-tens-of-milliseconds latency worldwide, no third-party rate-limit risk, and consistent availability backed by a 99.9% uptime target. Because country reference data changes rarely, responses are also highly cacheable on your side.
Region filtering accepts Africa, Americas, Asia, Europe, Oceania or Antarctic (case-insensitive) via /countries/v1/region/{region} or the region query parameter on /all. Currency filtering uses ISO 4217 codes such as EUR via /countries/v1/currency/{code}, and language filtering uses ISO 639-3 codes such as eng via /countries/v1/language/{code}.
Keep building
Related APIs
Query DNS records with support for all record types and reverse lookups, returning structured JSON responses.
Retrieve domain registration information, ownership details, expiration dates and registrar data for any domain.
Extract structured data from search engine results pages across multiple engines and device types.