Reference

API documentation

All endpoints are static JSON files. No authentication, no rate limiting, no SDK required. Fetch them with anything that speaks HTTP.

Supplement philosophy. Countries+ only carries fields that are not in RestCountries. For flag, current capital, population, languages, calling code, ISO codes, region — use RestCountries. Cross-link the two datasets via alpha2, alpha3, or numeric codes; all three are also in this API so the join is trivial.

Endpoints

Path Returns Sample
/countries/<ALPHA2>.json One country record (alpha2 = ISO 3166-1 alpha-2). /countries/IN.json
/index.json Compact array of every alpha2 code. Use for autocomplete. /index.json
/all.json Every full record in one file. /all.json
/by-region.json Records grouped by region (africa, americas, asia, europe, oceania). /by-region.json

Base URL: https://countries-plus.oriz.in · mirror at https://cdn.jsdelivr.net/gh/oriz-org/countries-plus-api@main

Record schema

Each /countries/<ALPHA2>.json file returns one record:

type CountryPlus = {
  alpha2:                string;            // ISO 3166-1 alpha-2, e.g. "IN"
  alpha3:                string | null;     // ISO 3166-1 alpha-3, e.g. "IND"
  numeric:               string | null;     // ISO 3166-1 numeric, e.g. "356"
  name:                  string;            // common name in English
  region:                string;            // africa | americas | asia | europe | oceania
  continent:             string | null;     // human-readable continent
  motto:                 string | null;     // national motto in original language
  motto_translation:     string | null;     // English translation
  motto_language:        string | null;     // language of the original motto
  national_anthem_title: string | null;     // title of the national anthem
  founding_date:         string | null;     // YYYY-MM-DD or YYYY
  former_capitals:       string[];          // e.g. ["Calcutta (1858-1911)"]
  former_names:          string[];          // e.g. ["Ceylon (until 1972)"]
  currency_name:         string | null;     // also in RestCountries; kept for self-containment
  currency_symbol:       string | null;     // e.g. "₹"
  sources:               string[];          // attribution
}

Sample — India

{
  "alpha2": "IN",
  "alpha3": "IND",
  "numeric": "356",
  "name": "India",
  "region": "asia",
  "continent": "Asia",
  "motto": "Satyameva Jayate",
  "national_anthem_title": "Jana Gana Mana",
  "founding_date": "1947-08-15",
  "currency_name": "Indian rupee",
  "motto_translation": "Truth alone triumphs",
  "former_capitals": [
    "Calcutta (1858-1911)"
  ],
  "currency_symbol": "₹",
  "sources": [
    "Wikidata / en.wikipedia (CC BY-SA 4.0)"
  ]
}

Cross-linking with RestCountries

Fetch both, merge by ISO code:

const [base, plus] = await Promise.all([
  fetch('https://restcountries.com/v3.1/alpha/IN').then(r => r.json()).then(a => a[0]),
  fetch('https://countries-plus.oriz.in/countries/IN.json').then(r => r.json()),
]);
const merged = { ...base, ...plus };
// merged now has flag, capital, population (from RestCountries)
// AND motto, motto_translation, founding_date, former_capitals (from us).

Coverage & missing data

Wikidata is the upstream. Some fields don't exist for some countries (e.g. former capitals only apply where the capital moved). When a field is unknown we set it to null or an empty array — we don't fabricate. See the homepage stats for per-field coverage.

Errors

The only possible error is 404 — unknown alpha2 code. There is no authentication, no rate limit, and no quota, so 401/403/429 cannot occur. CORS is wide open on both origins (Cloudflare Pages and jsDelivr).

License

Attribution: "Source: Wikidata / en.wikipedia (CC BY-SA 4.0)".