Countrydrop API reference

The REST Countries v2 and v3.1 endpoints, with the same paths, parameters and JSON. Base URL: https://pw-d20261017a29.plainwork-apps.workers.dev. Put it where https://restcountries.com was. The machine-readable description is at /openapi.json (OpenAPI 3.1).

Try it

Switching from restcountries.com

// before (now returns "This API version has been deprecated")
fetch("https://restcountries.com/v3.1/all?fields=name,flags")

// after: same path, same JSON
fetch("https://pw-d20261017a29.plainwork-apps.workers.dev/v3.1/all?fields=name,flags")

Old https://restcountries.eu/rest/v2/… URLs work too: keep the path and change the host (see restcountries.eu paths).

v3.1 endpoints

Every v3.1 endpoint accepts ?fields=: a comma-separated list of the field names to keep, for example name, cca2, cca3, flags, capital, currencies, languages, idd, population, region, latlng, timezones, translations. Names are not trimmed, which matches the original: name, capital (with a space) keeps only name.

v2 endpoints

Numbers and property order

Answers are written byte for byte the way the original wrote them, which matters for typed clients. The original was Java, and its decimal fields (area, latlng, capitalInfo.latlng, gini) were Java Doubles, so whole numbers keep a .0 and numbers of 10 million or more use Java's exponent form: "area":377930.0, "latlng":[36.0,138.0], "area":1.7098246E7 (Russia). Dart code such as json['area'] as double or List<double>.from(json['latlng']) depends on this. Property order and empty values follow the original's two serialisers too: answers without ?fields= leave out empty lists and empty strings (Iceland has no borders key) but write "postalCode":{"format":null,"regex":null}; answers with ?fields= keep empty lists ("borders":[]) and start with flags. We compared our output with 947 country records that people saved from the original API and committed to public GitHub repositories, wherever the data hasn't changed since: every one is byte-identical, and so are 925 saved area, latlng and gini values.

One v2 quirk is kept on purpose. List answers filtered with ?fields= always include "independent", and it is false unless you asked for that field. The original API did the same thing.

restcountries.eu paths

/rest/v2/… takes the old restcountries.eu URLs, which shut down in 2021, and serves them from the same v2 data. There, fields and codes may also be separated by ; as on .eu. This is best effort: the .eu service and its data were older than the v2 data served here.

Keys and limits

Days reset at 00:00 UTC. Every answer carries x-tier, x-ratelimit-limit and x-ratelimit-remaining (your own count). On top of the per-IP limit, all free requests together are capped at 40,000 a day, because our Workers plan has a daily cap. That total is counted in one place for everyone. If it is ever reached, every free request gets a 429 that says so until 00:00 UTC, even from an IP that has made no requests yet, and keys keep working. Key checks are cached for up to 10 minutes. If our key service can't be reached, a key verified in the last 10 minutes by the same Cloudflare instance keeps working; otherwise the request is answered on the free tier with the header x-key-status: unverified instead of failing. Lookups are case-insensitive, and the data never changes between requests, so cache answers on your side and you will rarely get near a limit.

Errors

Our errors are JSON with the same status and message keys the original used. Ours add error (a machine code) and docs.

A robust check in JavaScript:

async function countries(path) {
  const r = await fetch("https://pw-d20261017a29.plainwork-apps.workers.dev" + path);
  const body = await r.text();
  let data;
  try { data = JSON.parse(body); } catch { throw new Error("Temporary error (" + r.status + "), retry later"); }
  if (r.status === 404) return [];                    // nothing matched
  if (!r.ok) throw new Error(data.message);           // 400, 401, 429 ...
  return Array.isArray(data) ? data : [data];
}

Python:

import requests
r = requests.get("https://pw-d20261017a29.plainwork-apps.workers.dev/v3.1/alpha/jp",
                 params={"fields": "name,capital"}, timeout=10)
print(r.json() if r.headers.get("content-type", "").startswith("application/json") else "retry later")

Where the data comes from

The data is REST Countries' own countriesV3.1.json (last changed 25 Feb 2026) and countriesV2.json (12 Nov 2025), from its MPL-2.0 source repository. The values are unchanged; they are written the way the original API wrote them (see numbers and property order). The v2 records carry only the fields the original v2 classes had. The endpoint logic was ported from the same repository's Java code. We also wrote a second, separate implementation of that logic in Python, and 8,500+ queries built from every country's codes, names, capitals, currencies, languages and demonyms give the same matches in both. Both were written by us, so the byte comparison with saved original responses is the outside check. Flag and coat-of-arms image URLs point to flagcdn.com and mainfacts.com, as they always did. Population and other fast-moving figures are frozen at that release. Countrydrop is not affiliated with REST Countries.

Deliberate differences: /all without fields returns everything, as it did until June 2025, where the final API answered 400. /v2/regionalbloc/ matches a bloc's acronym even when the bloc lists no other acronyms; the original code skipped those blocs. Results are returned in data-file order, where the original's v3.1 order was arbitrary.