Docs
Documentation for the REST Countries API family: one account, shared API keys, one monthly quota across every API.
Introduction
REST Countries is a family of read-only HTTP APIs for reference data: every endpoint returns JSON over HTTPS, authenticates with a single bearer token, and needs no SDK. The Countries API serves structured country data; the Currencies API handles conversion and exchange rates. All APIs share one account, your API keys, and one monthly request quota. Authentication, request limits, rate limiting, and account states work the same everywhere and are covered below.
APIs
Countries API. Structured, normalized data for every country: names, ISO codes, capitals, currencies, languages, flags, borders, geography, and political leaders, 90+ fields in all, served from a small set of list, lookup, and search endpoints. See the Countries API reference for the full field catalog, query parameters, and runnable examples.
New Currencies API. Currency conversion and exchange rates: convert an amount from one currency to one or many others, pull a base's full rate table, or list every supported currency and symbol, across both fiat and crypto. See the Currencies API reference for endpoint details, parameters, and response objects.
Authentication
Every 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:
curl "https://api.restcountries.com/countries/v5?q=Canada&api-key=YOUR_API_KEY&pretty=1"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 computed
from live data, and a friendly notice: no account required, no quota burn, nothing
logged against any account:
curl "https://api.restcountries.com/countries/v5?q=Canada&api-key=rc_live_demo&pretty=1"
The notice lives under data._demo.message and
data._demo.signup_url, pointing at
restcountries.com/sign-up. The demo is scoped to the endpoint you hit, so
every endpoint, across every API, returns a sample shaped like that route's real response.
Sign up to get a real key with full access.
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.
Request limits
REST Countries applies a monthly request quota to every account. Quotas reset on your monthly billing anniversary (the same day of each month as your sign-up date), and requests to every API (Countries and Currencies alike) count against the same quota. There's also a separate throughput ceiling, covered under Rate limiting. The exact monthly cap depends on your plan:
| Plan | Monthly limit |
|---|---|
| Free | 500 |
| Personal | 25,000 |
| Professional | 100,000 |
| Startup | 200,000 |
| Business | 750,000 |
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.
Rate limiting
Separate from your request limits, there's a throughput
ceiling on how quickly you can call the APIs. Sustained traffic above
20 requests per 10 seconds is rejected with a
429 Too Many Requests. The ceiling applies to your traffic
as a whole, not per API.
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
ceiling clears it.
Account states
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.
| State | Meaning |
|---|---|
pendingApproval | The account is in a brief manual-review queue
while we confirm the sign-up is genuine. Fewer than 1% of sign-ups land
here, and approval is usually within 12 hours: the account flips to
active automatically once cleared. |
disabled | We've detected malicious activity on the account (key abuse, scraping patterns clearly outside normal use, etc.) and have shut it off. If you think this is in error, contact support and we'll review the situation and reinstate where appropriate. |
frozen | The account has exceeded its monthly request limit by a meaningful margin past the soft-limit grace period. Requests are paused until either the quota rolls over on the next monthly billing anniversary or the account is upgraded to a plan whose ceiling covers the usage. No data is lost; the freeze just blocks new requests. |
Versioning
Every API ships breaking changes as a new path version (/v1,
/v2, …), and each API versions independently. The
Countries API is currently at v5, the first
version we consider long-term stable; versions
v1–v4 were public iterations and
have been deprecated. The Currencies API is at
v1, long-term stable from launch.
Current versions stay live indefinitely. When a future major version of an API eventually ships (only for a genuine breaking change we can't ship additively), the version you built against keeps serving alongside it, and the same commitment carries forward to every version after. Anything you build today doesn't have to follow us forward to keep working.
For the Countries API's 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/countries/api-versions.
Acceptable use
REST Countries is designed to power features inside your own product: country pickers, geographic search, onboarding flows, price localization, checkout currency conversion, dashboards, anywhere you'd otherwise hand-curate a list of countries or stitch together exchange-rate feeds. 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 data for offline use. Caching responses for performance is fine, up to three days, per the Terms. Pulling a full dataset down once and using your local copy from then on isn't, and neither is serving conversions from rates cached past that window.
- 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- or currency-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.
Data requests & corrections
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? Each API documents its own freshness: static country fields are reviewed weekly against ISO and UN sources, with the rest syncing every 4 hours after multi-source reconciliation (see Field reference), and exchange rates refresh on a cadence set by your plan (see Freshness & as_of). But the world moves and feeds occasionally lie. If a value looks off, send it our way: include the country or currency pair, 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.