# REST Countries

> REST Countries is a read-only data API family: a Countries API (250+ countries, 90+ fields each) and a Currencies API (currency conversion and exchange rates, fiat and crypto), sharing one key and one quota at 99.995% uptime.

REST Countries is a read-only HTTP API served as JSON over HTTPS from a long-term-stable, license-cleaned dataset. It spans two APIs that share one account, one API key, and one monthly request quota: the Countries API (`/countries/v5`) for structured country data, and the Currencies API (`/currencies/v1`) for currency conversion and exchange rates across fiat and crypto. Each API versions independently: additive changes ship inside the current major, and breaking changes would get a new major. Authentication is `Authorization: Bearer {key}` on every request; sign up at https://restcountries.com/sign-up for a key. A demo key `rc_live_demo` works on any endpoint without an account (returns sample payloads, no quota burn).

## Quick reference

### Countries API

- Base URL: `https://api.restcountries.com/countries/v5`
- Auth header: `Authorization: Bearer {api-key}` (or `?api-key={api-key}` for browser-side testing)
- Default page size: 25; max 100 via `?limit=`
- Pretty JSON: append `?pretty=1`
- Trim response: `?response_fields=names.common,codes.alpha_2` (dot-path projection)
- Drop heavy branches: `?response_fields_omit=names.translations`
- Full-text search across searchable properties: `?q=`
- Per-property filter chains with AND-semantics: `?region=Europe&landlocked=1`
- Aggregate searches: `/code?q=` spans every code property; `/name?q=` spans common/official/native/alternates

### Currencies API

- Base URL: `https://api.restcountries.com/currencies/v1`
- Auth: same bearer token (or `?api-key=`); draws on the same account quota and the same 20 req/s edge limit
- Convert: `/convert?from=USD&to=EUR&amount=100`; `to` takes up to 5 comma-separated targets, `amount` defaults to 1, all-or-nothing on any unknown code
- Rates: `/rates/USD` (or `/rates?base=USD`); full table of units per one unit of the base, and every key is itself a queryable base
- Symbols: `/symbols`; the supported-currency catalog (`code`, `name`, `symbol`), the canonical list of what the API supports
- Both fiat and crypto codes (e.g. `USD`, `EUR`, `BTC`, `ETH`); codes case-insensitive on input, echoed uppercase
- Snapshot-backed: every convert/rates object carries an `as_of` stamp; refresh cadence is 24h (free) / 1h (paid)
- Pretty JSON: append `?pretty=1`

## Docs

- [Docs hub](https://restcountries.com/docs): entry point to both APIs, plus the shared account-level topics: authentication, request limits, rate limiting, account states, and versioning.
- [Countries API](https://restcountries.com/docs/countries): the full `/v5` country-data reference: list and single-country lookup by alpha-2, alpha-3, name, or code, full-text (`?q=`) and per-property search, response-field projection, pagination, and the 90+ field catalog.
- [Data sources](https://restcountries.com/docs/countries/data-sources): which upstream registries feed each field and the refresh cadence (static fields cross-checked weekly against ISO/UN; dynamic fields synced every 4 hours via multi-source reconciliation).
- [API versions](https://restcountries.com/docs/countries/api-versions): long-term-stable versioning policy and how additive vs breaking changes are handled.
- [Currencies API](https://restcountries.com/docs/currencies): the read-only currency conversion and exchange-rate API: the convert, rates, and symbols endpoints, snapshot-backed rates with `as_of` freshness stamps, and both fiat and crypto codes.
- [Webhooks](https://restcountries.com/docs/webhooks): signed POSTs when dynamic fields change, signature verification, retry semantics, idempotency, and local testing.
- [Supported countries](https://restcountries.com/countries): browsable list of every country the Countries API covers, each linking to a per-country page.
- [Supported currencies](https://restcountries.com/currencies): browsable list of every currency the Currencies API supports, each linking to a per-currency page with its exchange rate.

## Account

- [Plans](https://restcountries.com/plans): tiers, request limits, and feature matrix.
- [FAQ](https://restcountries.com/faq): common questions about freshness, recognition edge cases, pricing, and supported patterns.
- [Roadmap](https://restcountries.com/roadmap): in-progress, considering, and researching items.
- [Changelog](https://restcountries.com/changelog): month-by-month additive changes inside `/v5`.
- [Support](https://restcountries.com/support): contact form for data corrections, feature requests, and account issues.