Documentation

Three steps before you read another word of docs. None require an account.

1. Fire a live request from this page. Click the button below. The response slides open in the Explorer panel.

// Demo key: no account required.
const response = await fetch(
  'https://api.restcountries.com/countries/v5/names.common/Canada',
  { headers: { 'Authorization': 'Bearer rc_live_demo' } }
);
const data = await response.json();

Run this request →

2. Or run it from your terminal. Click the snippet to copy, then paste anywhere curl lives.

curl "https://api.restcountries.com/countries/v5/names.common/Canada" \
  -H "Authorization: Bearer rc_live_demo"

3. Trade the demo key for a real one. The demo returns a friendly notice, not the dataset. Sign up for a key with full access: free tier, no card required.

Get an API key Log in

REST Countries exposes one resource (countries) across a small surface of endpoints. The dataset covers 80+ normalized fields per country (codes, capitals, currencies, languages, borders, geography, memberships, locale conventions, and links). Static fields are reviewed weekly against ISO and UN sources; dynamic fields such as population sync every 4 hours. Premium dynamic fields such as leaders use the same cadence and are available on paid plans.

• Read-only. All endpoints are GET. There is no POST/PUT/DELETE surface.
• JSON-only responses. Content-Type: application/json on every response. Response shapes follow the conventions of the JSON:API specification: successful payloads sit under a top-level data key (with response metadata nested inside data.meta when relevant), and failures come back under errors as an array of objects carrying a message. We don't claim strict spec compliance, but if you've worked with JSON:API the shape will feel familiar.
• Stable v5. Breaking changes will ship as a new version (e.g. /v6), with indefinite support for previous versions. See Versioning.

Sign up to get an API key, then paste this into your terminal:

curl "https://api.restcountries.com/countries/v5/names.common/Canada" \
  -H "Authorization: Bearer {{your_api_key}}"

You'll get a single-record data.objects array back. From there, jump to the endpoint sections for the full surface, or browse the Field reference to see what's in each record.

Every Countries endpoint requires an API key. The recommended form is a bearer token in the Authorization header:

Authorization: Bearer {{your_api_key}}

The bare form (no Bearer prefix) is also accepted for clients that can't easily inject the scheme:

Authorization: {{your_api_key}}

And as a last resort, the key can be passed as an api-key query parameter (useful for browser-based experiments), but be aware these can leak into server logs and browser history:

# Less safe, but supported
curl "https://api.restcountries.com/countries/v5/names.common/Canada?api-key={{your_api_key}}"

Try it without an account

Use the demo key rc_live_demo against any endpoint to verify the API is reachable. Demo requests return HTTP 200 with the normal response shape, a sample object when one is available, and a friendly notice: no account required, no quota burn, nothing logged against any account:

curl "https://api.restcountries.com/countries/v5?api-key=rc_live_demo"

The notice lives under data._demo.message and data._demo.signup_url, pointing at restcountries.com/sign-up. Sign up to get a real key with full access to the dataset.

Browser usage & CORS

Browser-side requests are blocked by default unless the API key allows the page's origin hostname. Add comma-separated hostnames on the API Keys page before using a key from frontend code.

Enter hostnames only, without protocol, port, or path (e.g. example.com, app.example.com, or localhost). IPv4 addresses like 127.0.0.1 are also supported. When the browser sends Origin: https://app.example.com, the API compares app.example.com against the API key's allowed hostnames.

Requests without an Origin header are treated as server-to-server requests and are not affected by CORS settings. The demo key works from the docs, dashboard, and other supported REST Countries web origins.

All endpoints live under:

https://api.restcountries.com/countries/v5

The v5 path segment is the API version. REST Countries commits to backwards-compatible additions within a major version (new fields, new endpoints, new query params).

Business-plan customers also get a dedicated EU-region endpoint at a separate hostname (eu-west-1) for in-region routing.

Returns a paginated list of all countries. Defaults to limit=25; max limit is 100 (anything higher returns 400). Adding q or any searchable property as a query parameter narrows the list. See Search.

Free-text search across every searchable property. Substring match, case-insensitive. + and %20 are both decoded as spaces. An empty q returns 400.

Combinable with one or more property filters as /countries/v5?q=...&{property}=... to AND-narrow the result set. For searches scoped to a named property bundle (e.g. all name fields, all code fields), see Aggregate. For a single-property search, see Search by property.

Search across a named bundle of properties in one call. An object matches if any one of the underlying properties contains q (substring, case-insensitive). Two aggregates are predefined:

Note: names.translations is intentionally excluded from the name aggregate. Translations cover dozens of languages per country, so substring matches there produce too many false positives to be useful in a generic name search. Use Search by property against names.translations directly if you need to query translations specifically.

Empty q returns 400. If the path segment isn't a known aggregate name, the request falls through to Search by property.

Look up countries by any readable property. Works equally well for unique identifiers (codes.alpha_2/CA, names.common/Canada), group properties (region/Europe), and reverse lookups on array fields (borders/CAN returns the countries that border Canada). + and %20 are both decoded as spaces, so capitals/new+delhi, capitals/new%20delhi, and capitals/new delhi all resolve.

Append ?q=... to further narrow the matched set against the searchable properties (e.g. /region/Europe?q=germ).

curl "https://api.restcountries.com/countries/v5/capitals/Tokyo" \
  -H "Authorization: Bearer {{your_api_key}}"

{
  "data": {
    "objects": [
      { "names.common": "Japan", "codes.alpha_3": "JPN", "flag.emoji": "🇯🇵" }
    ],
    "meta": { "total": 1, "count": 1, "limit": 25, "offset": 0, "more": false }
  }
}

Returns 404 for non-existent or non-readable properties (e.g. population, flag.emoji, government_type). See Field reference for the per-field readable / searchable flags.

Substring search within a single searchable property. /countries/v5/names.common?q=ger finds every country whose common name contains "ger". Case-insensitive. An empty q returns 400; a non-existent or non-searchable property returns 404.

Premium searchable properties, such as leaders, are available on Personal plans and above. Free-plan accounts receive 403 when searching or filtering by those properties.

If the path segment is the name of an aggregate (name or code) instead of a real property, the search fans out across that aggregate's underlying property list. See Search.

Every country record carries the following fields. Static fields are sourced from ISO, UN, and Wikidata and reviewed weekly. See Data sources for the full list of registries we cross-check against. Example response bodies in the endpoint sections abbreviate map-shaped fields (currencies, languages, demonyms, etc.) for readability; see each field's type below for the wire shape.

Data syncs every 4 hours. Fields tagged dynamic (e.g. population, leaders, government_type) are recomputed on a 4-hour cadence by reconciling values across multiple authoritative upstream sources; the published value only updates once at least two of those sources agree on it. That extra confirmation step costs a small amount of latency on breaking changes but means a single bad feed (a typo, a reverted Wikipedia edit, an upstream outage) won't pollute your response.

Premium data. Fields tagged premium are available on Personal plans and above. Free-plan list and read responses replace those fields with an upgrade notice; free-plan searches or filters against premium fields return 403.

In broader country responses, the field value is replaced in place. For example, leaders data will show the following (for free plans):

{
  "leaders": [
    {
      "message": "data.leaders is only available on paid plans. Go to https://restcountries.com/plans to make updates to your account."
    }
  ]
}

Direct searches, filters, and lookups against the premium field return an error response. For example, attempt to search or filter by leaders will show the following (for free plans):

{
  "errors": [
    {
      "message": "The leaders field is available only on paid plans and cannot be used as a search, filter, or lookup field on your current plan. Request broader country data to receive the fallback value. Go to https://restcountries.com/plans to make updates to your account."
    }
  ]
}

Multi-object responses are returned in a stable order, sorted alphabetically (ascending) by names.common. The same query returns the same objects in the same positions across requests, which means limit and offset can be used to page through a result set without races or duplicates.

Custom sort parameters aren't currently supported. If you have a use case that needs a different order (most populous first, by region then name, etc.), let us know.

Every endpoint that returns objects accepts limit (1–100, default 25) and offset (default 0). The response carries a data.meta block describing the slice, so you can iterate without tracking position client-side:

{
  "data": {
    "objects": [ ... ],
    "meta": {
      "total":  249,
      "count":  25,
      "limit":  25,
      "offset": 0,
      "more":   true,
      "request_id": "<request-id>"
    }
  }
}

total is the total matched count after filters; count is the size of the returned slice; more is shorthand for "there are records past this page". Out-of-bounds offsets return an empty objects array (status 200), not a 404. A limit above 100 (or below 1) returns 400.

Error responses use standard HTTP status codes plus a JSON body that names what went wrong. Each entry in the errors array includes a message describing the failure.

{
  "errors": [
    {
      "message": "Limit must be an integer between 1 and 100."
    }
  ]
}

Separate from your request limit, there's a per-second ceiling on how quickly you can call the API. Sustained traffic above 20 requests per second is rejected with a 429 Too Many Requests.

This ceiling is enforced by Cloudflare at the edge, in front of the API, so the 429 is returned before the request ever reaches the API itself. If you hit it, back off briefly and retry. Spreading bursts out under the per-second ceiling clears it.

REST Countries applies an edge throughput limit and a monthly account quota. Sustained traffic above 20 requests per second is rejected with 429 Too Many Requests before it reaches the API. Monthly quotas are applied per account and reset on your monthly billing anniversary (the same day of each month as your sign-up date). The exact monthly cap depends on your plan:

To change plans (upgrade for a higher monthly cap, or step down if your usage has dropped), head to the Plans page. New ceilings apply immediately on upgrade; existing keys keep serving without re-issuing.

Limits are soft. Going over your monthly cap doesn't immediately stop the API; we send email alerts at 50%, 80%, and 100% of your cap so overage is never a surprise. After you cross 100% there's a short grace period during which requests continue to succeed, giving you time to upgrade or wait for your monthly billing anniversary to reset the quota. Only if the grace period elapses without an upgrade or reset do subsequent requests start returning 403 Forbidden: the account is frozen until your next monthly billing anniversary. As soon as the quota rolls over on that anniversary (or you upgrade), keys go back to serving immediately. See Account states for what happens after sustained overage.

Almost every account stays in the default active state for its entire lifetime. The states below cover the handful of cases where an account needs a different posture.

REST Countries ships breaking changes as a new path version (/v5, /v6, …). The current version is v5, and it's the first version we consider long-term stable. Versions v1–v4 were public iterations and have been deprecated. See the legacy API deprecation page for migration guidance.

v5 stays live indefinitely. When a future major version eventually ships (only for a genuine breaking change we can't ship additively), v5 keeps serving alongside it, and the same commitment carries forward to every version after. Anything you build against v5 today doesn't have to follow us forward to keep working.

For the full architectural background (why v1–v4 couldn't be kept stable, what v5's stability promise covers, and how account-holders get notified about new endpoints, fields, and future versions), see /docs/api-versions.

Subscribe one or more URLs to receive a signed POST when REST Countries data changes (e.g. when a country's leaders updates after an election or its population shifts after a World Bank refresh). Webhooks are a Business plan feature.

Full reference (event types, payload schemas, signature verification, delivery and retry semantics, idempotency, and local testing) lives on its own page: /docs/webhooks.

REST Countries also provides a free global CDN for country flag images. It serves 254 flags in PNG, JPG, GIF, and SVG formats, with raster widths from w160 through w2560. Each flag has 45 raster URL variations plus one SVG, which means 11,684 image URLs are available for free across the CDN. No account is needed, no API key is required, and the CDN can be used entirely anonymously.

That keeps teams from having to generate, resize, convert, store, and invalidate thousands of flag image variations themselves.

<img src="https://flags.restcountries.com/v5/w320/ca.png" alt="Canada flag">

Flag requests are delivered from Cloudflare edge nodes with cache rules for stable image URLs, with CloudFront as the fallback source and S3 behind that as the durable origin. The flag CDN is cookie free and GDPR compliant, and it is designed for direct browser use with no tracking.

Open the Flag CDN picker →

REST Countries' dataset is stitched together from authoritative public registries, multilateral bodies, and well-maintained open-data projects. Static fields are cross-checked against ISO and UN baselines weekly; other fields are synced every 4 hours by reconciling multiple upstream feeds against each other before a value is published. The full list of where every field comes from (registry by registry, with the schema properties each one feeds) lives on its own page.

View the full source list →

REST Countries is designed to power features inside your own product: country pickers, geographic search, dashboards, onboarding flows, anywhere you'd otherwise hand-curate a list of countries. That's exactly what we built it for, and we're happy to see what you ship.

One expectation worth stating plainly: the free tier is meant for evaluation, prototyping, and personal projects. If REST Countries ends up powering something commercial (a product your customers pay for, or a part of how your business operates), we ask that it run on one of the paid plans. That's what funds the data reconciliation and keeps the API fast for everyone.

Two patterns, though, fall outside what's covered by your subscription:

• Snapshotting the dataset for offline use. Caching responses for performance is fine, up to three days, per the Terms. Pulling the full dataset down once and using your local copy from then on isn't.
• Building a competing data product. Using REST Countries inside an app is great. Re-exposing the data as your own API, dataset download, or country-data feed isn't.

If you have an interesting use case that brushes up against either of these, just talk to us. We'd rather hear about it than not, and there's almost always a way to make it work.

Need a field, dataset, or attribute we don't currently expose? We add data based on what customers ask for. Tell us what you'd find useful and we'll consider it for a future release.

Spotted something stale or wrong? Static fields are reviewed weekly against ISO and UN sources, and other fields sync every 4 hours after multi-source reconciliation (see Field reference), but the world moves and feeds occasionally lie. If a value looks off, send it our way: include the country, the property path, what the API returned, and what you believe the correct value is (with a source link if you have one). We'll verify against upstream and ship a correction or roll the offending feed off our reconciliation list.

Request data Report incorrect data