REST Countries

Docs›Legacy API Deprecation.

If you're reading this after a request to /v1, /v2, /v3, or /v4 failed, we're sorry.

We were forced to take down those endpoints.

It happened because the previous developer of this API didn't keep an email list of who was calling it, or split the traffic onto a subdomain that would have allowed the old versions to be maintained independently. This page is the warning we couldn't send before.

The data is still here. The catch is that the new endpoint isn't a drop-in replacement. Some field names have changed, along with the response structure / shape. Most integrations will need a small mapping pass on the response side, but we don't think it should take more than 15 - 20 minutes.

That being said, we are making this committment: /v5 will is the first version of the API that we consider long-term stable, and will be kept up indefinitely.

What you got back

The API now returns the below response:

{
  "success": false,
  "data": null,
  "errors": [
    {
      "message": "This API version has been deprecated. Please visit https://restcountries.com/docs/legacy-api-deprecation to migrate to our new version."
    }
  ]
}

No payload behind it. Every request to the old versions returns the same response and error array now. If your code was checking a successful body, that's why it broke.

Get back online

  1. Create a free account. No credit card. The free tier covers 500 requests /mo, which fits most legacy callers comfortably.
  2. Replace the old version (/v1, /v2, /v3, or /v4) in your URL with /v5, and send your API key in an Authorization: Bearer YOUR_KEY header.
  3. Update the part of your client that reads the response. Field names and the overall response structure changed between v1–v4 and v5. Every field the old API exposed still exists, but you'll need to map the new shape onto whatever your code expects. The v5 docs document every endpoint and field; a side-by-side compare against your current parsing should make the changes obvious.

Trigger a sample request Get a free API key →

Once your account is set up, you can expect a stable, high-performant API that will be kept up indefinitely

If you're a high-volume caller

If you've been on v1–v4 for a while and your traffic is well past what the standard free tier covers, talk to us. We're offering an enhanced free plan through the migration window: still free, no credit card required.

Talk to us

Mention which legacy version you've been calling and your rough monthly request volume, and we'll match a tier that lines up.

Why this happened the way it did

The previous developer, who is no longer maintaining the API, was running it unmetered and unauthenticated. That's why you didn't get any warning before today: there was no way to reach out.

Once you're on v5, that communication channel exists in both directions. You'll hear about new endpoints, new data fields, and new versions before they affect your code, and your feedback actually lands somewhere. That's the upside of the move. The architectural reasons v1–v4 couldn't be kept stable, plus the long-term commitment around v5, live on /docs/api-versions.