Docs›API versions

If you got here because a v1–v4 request just stopped working, start at /docs/legacy-api-deprecation. This page is the architectural background: why v1–v4 can't be kept stable, what /v5's long-term stable promise means, and how future deprecations will be communicated.

Where each version stands

Why v1–v4 can't be kept stable

The previous 4 versions of REST Countries shipped without three fundamental elements required for the long-term stability of an API. They included:

• Authentication. v1–v4 were fully open: no API Keys, no headers, no ?api-key=. That meant that the APIs couldn't secure themselves against bots or malicious traffic. It also meant that updates to the API couldn't be effectively communicated to users.
• API hostname seperation. v1–v4 operated against the root restcountries.com domain. That meant that requests couldn't easily be separated to run against more resilient servers.
• Field limitations. v1–v4 limited responses to at most 10-fields when making broad requests. That meant developers needed to make multiple requests to access all the data they needed.

These have all been resolved with /v5, however it's required us to end support for those API versions.

What's different about v5

/v5 is committed to staying live indefintely. This is because the three fundamental issues above have been resolved:

• Authentication. v5 now supports API Keys (Authorization: Bearer preferred, with a ?api-key= query-string fallback for browser experiments) which will allow us to update users when there are updates to the API (including new data being added, or new versions forthcoming).
• API hostname seperation. All requests are now served from api.restcountries.com. This means we can better protect the endpoint, and scale it up as needed. We aim for 99.999% uptime, which is only possible with this new hostname.
• Field limitations. There are no longer any limits on the amount of data you can request for a country.

If you have any questions about these changes. please reach out. We'll response within 24 hours.

Migrating from v1–v4 to v5

Three steps:

1. Create an account if you don't already have one. The free tier covers 500 requests /mo with no credit card.
2. Read the v5 docs. Every endpoint and field is documented, including the aggregates, the response_fields response-shape allowlist, the q free-text search, and the per-property filters that v1–v4 didn't support.
3. Update your client to call /v5 with Authorization: Bearer YOUR_KEY in the request header. The bare Authorization: YOUR_KEY form (no Bearer prefix) is also accepted.

Questions

The FAQ covers the common ones. For anything tied to your specific migration, reach out via support.