How do I authenticate requests to the Countries API?

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 apicodex.io/register.

Which country codes can I look up by?

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.

How are the flag images provided?

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.

How are calling codes normalized?

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.

Can I reduce the size of list responses?

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.

How fast and reliable is the API?

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.

What regions, currencies and languages can I filter by?

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

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.

Get a free API key Read the docs

Free tier included, no credit card required. One key works across every API.

Free calls / month: 1,000
Countries: 250+
Response Time: <50ms
Uptime SLA: 99.9%

Get your free API key

1,000 free calls on the free plan

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

MCP · for your agent

Hand the Countries API to your agent

Connect Claude, Cursor or any MCP client once, then ask in plain words. Your agent finds this API, reads its docs and makes the call: 1 credit per call, the same as REST, from your team's balance.

Connect your agent

Build a checkout country picker

“Build the country dropdown for our European checkout: country names, ISO codes, flag emoji and dialing codes.”

list_apis · get_api_docsfree

api_request GET /countries/v1/all?region=Europe&fields=name_common,cca2,flag_emoji,calling_codes 1 cr

Every European country with name, ISO code, flag and dialing code, ready to paste in.

List every country using the euro

“Which countries use the euro? I need the list to set EUR as the default currency in our billing settings.”

list_apis · get_api_docsfree

api_request GET /countries/v1/currency/EUR 1 cr

All countries that use EUR with their ISO codes, for your billing currency defaults.

Place an unfamiliar phone number

“A lead's number starts with +971. Which country is that, what currency do they use, and is the full number valid?”

list_apis · get_api_docsfree

api_request GET /countries/v1/calling-code/971 1 cr

+ Phone Number Validation & Formatting API5 cr

The United Arab Emirates with its capital and currency, plus a validity check on the number.

$ claude mcp add --transport http apicodex https://mcp.apicodex.io

Illustrative asks; the calls and prices are real. Claude, Cursor, VS Code and Windsurf setup: mcp.apicodex.io

Try it

Build the request for your data

Edit the parameters below and see the exact request and curl command you'd send. No key required to preview.

GET /countries/v1/code/AW

Open in Playground

Parameters

apikey

Request · HTTP

GET /countries/v1/code/AW?apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

Response · JSON 200 OK

{
"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"]
}
}

Run it with your key

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

url

https://api.apicodex.io/countries

Authentication

Authenticate by passing your API key as the ?apikey= query parameter on every request:

headers

https://api.apicodex.io/countries/v1/code/AW?apikey=YOUR_KEY

Request and response

Illustrative values. Confirm current endpoint behavior, quotas, and data freshness in the API documentation before production use.

request · http

GET /countries/v1/code/AW?apikey=YOUR_KEY HTTP/1.1
Host: api.apicodex.io

response · json

{
"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

curl --request GET \
  --url 'https://api.apicodex.io/countries/v1/code/AW?apikey=YOUR_KEY'

JavaScript/Node.js

const params = new URLSearchParams({ apikey: 'YOUR_KEY' });

const url = 'https://api.apicodex.io/countries/v1/code/AW?' + params;

try {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data.country);
} catch (error) {
  console.error(error);
}

Python

import requests

url = "https://api.apicodex.io/countries/v1/code/AW"

querystring = {"apikey": "YOUR_KEY"}

response = requests.get(url, params=querystring)

print(response.json())

Available Endpoints

GET /v1/all

List every country (enriched). Optionally filter by region, project a subset of fields, and cap results with limit (default 300).

/v1/all?region=Oceania&fields=name_common,cca2,calling_codes&apikey=YOUR_KEY

GET /v1/code/{code}

Resolve one country by cca2, cca3, ccn3 or cioc, tried in that order, case-insensitive.

/v1/code/AW?apikey=YOUR_KEY

GET /v1/search

Partial, case-insensitive name search over name_common, name_official and altSpellings. Ranked exact > prefix > substring.

/v1/search?name=united&apikey=YOUR_KEY

GET /v1/region/{region}

List countries in a region: Africa, Americas, Asia, Europe, Oceania or Antarctic (case-insensitive).

/v1/region/Europe?apikey=YOUR_KEY

GET /v1/currency/{code}

List countries using an ISO 4217 currency code (case-insensitive).

/v1/currency/EUR?apikey=YOUR_KEY

GET /v1/language/{code}

List countries with an ISO 639-3 language code (case-insensitive).

/v1/language/eng?apikey=YOUR_KEY

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

/v1/calling-code/1?apikey=YOUR_KEY

Query Parameters

Required parameters

apikey Your API key, passed as a query parameter on every request.
name Name substring to search for (required on /search).
code Path value: ISO code, currency code, language code, or calling code depending on the endpoint.
region Path value on /region: Africa, Americas, Asia, Europe, Oceania or Antarctic.

Optional parameters

fields Comma-separated field names to project, e.g. name_common,cca2,calling_codes (on /all).
region Filter /all results by region (case-insensitive).
limit Max results, clamped 1..500. Default 300 for list endpoints, 50 for /search.

Pricing

Countries API Pricing

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'll recommend the cheapest plan that covers it.

Requests per month 10,000

Recommended plan

Starter

$29.99 /month

Credits used

Credits included

Cost per 1K requests

Choose Starter

Free

1,000 credits · ~1,000 requests/mo · 2 rps

All APIs included
No credit card required
Full documentation and examples
MCP server for your AI agents
Up to 5 active API keys

Start for free

Starter

Popular

$29.99 /month

50,000 credits · ~50,000 requests/mo · 10 rps

All APIs included
Email support
Usage dashboard and analytics
MCP server for your AI agents
Up to 5 active API keys

Start with Starter

Pro

$99.99 /month

250,000 credits · ~250,000 requests/mo · 25 rps

All APIs included
Priority support
MCP server for your AI agents
Up to 5 active API keys

Start with Pro

FAQ

Countries API

Key features

Built for

Hand the Countries API to your agent

Build a checkout country picker

List every country using the euro

Place an unfamiliar phone number

Build the request for your data

Countries API Documentation

Base URL

Authentication

Request and response

Code examples

Available Endpoints

GET /v1/all

GET /v1/code/{code}

GET /v1/search

GET /v1/region/{region}

GET /v1/currency/{code}

GET /v1/language/{code}

GET /v1/calling-code/{code}

Query Parameters

Required parameters

Optional parameters

Countries API Pricing

Free

Starter

Pro

Need a different plan?

Frequently asked questions

Related APIs