Changelog

Additive changes shipped inside /v5. Breaking changes would land as a new major version instead. See Versioning.

Jun 2026

Launched /v5 goes public alongside the new restcountries.com: first public-facing build of the docs, marketing pages, and developer onboarding flow

Launched Free Flag CDN: public domain country flag images served from a global CDN, covering 254 flags and 11,684 generated image URLs across PNG, JPG, GIF, SVG, sizes, and shapes without requiring an account or API key

Launched Per-key CORS controls: browser-origin requests are blocked by default unless the key allows the origin hostname, so browser-based apps can restrict where a key is accepted without proxying every request through their own backend (see Browser usage & CORS)

May 2026

Launched Account state machine: disabled, frozen, and pendingApproval, each with documented behaviour and a clear path back to active (see Account states)

Launched Webhooks: signed POSTs when dynamic fields like leaders or population change (see /docs/webhooks)

Launched API key management: issue, revoke, and expire keys from the dashboard

Launched Self-serve billing: plan checkout, upgrades, downgrades, and billing-cycle switches from the billing page

Launched Account dashboard with usage graphs: request volume, status-code mix, and top endpoints

Launched Account, billing, and webhook notification emails

Added members: convenience array of every organization the country belongs to, mirroring the memberships.* booleans in a single iterable

Added classifications: convenience array rolling up the classification.* flags into a single iterable for easier consumption

Added leaders: current head of government and head of state, synced every 4 hours from authoritative sources

Added memberships.*: booleans for UN, UN observer, African Union, Arab League, ASEAN, BRICS, Commonwealth, EU, Eurozone, G7, G20, NATO, OECD, OPEC, and Schengen

Added classification.*: sovereign, disputed, iso_status, un_member, dependency, and dependency_type (crown dependency, overseas territory, SAR, etc.)

Added parent.alpha_2 and parent.alpha_3: explicit parent linking for dependent entities like overseas territories, crown dependencies, and special administrative regions

Added government_type: the country's political system (federal republic, constitutional monarchy, etc.)

Added capitals with role flags: primary, constitutional, administrative, executive, legislative, and judicial, so countries with split-capital arrangements are represented properly

Added economy.gini_coefficient as a year → value map: historical Gini tracking instead of a single point-in-time value

Added date.fiscal_year_start.government, .corporate, and .personal: three separate fiscal-year starts per country, since they rarely line up

Added date.start_of_week and date.academic_year_start: calendar metadata for scheduling and localization use cases

Added postal_code.format and postal_code.regex: ready-to-use validation patterns for address forms

Added number_format.decimal_separator and number_format.thousands_separator: locale-correct numeric formatting per country

Added codes.fips and codes.gec: rounding out the country-code surface alongside the existing alpha_2, alpha_3, ccn3, cioc, and fifa

Added flag.html_entity and flag.description: on top of the existing emoji, Unicode, PNG, and SVG variants of the flag

Added links.wikipedia and links.official: on top of the existing links.google_maps and links.open_street_maps

Added uuid: stable per-country identifier that survives code revisions, useful for primary keys in downstream systems

Apr 2026

Released /v5: Bearer auth, q + per-property filters, aggregates, response_fields shaping, pretty, limit / offset pagination, and the full 80+ field surface

Launched /docs: full REST Countries documentation site with an in-page Explorer for firing live requests against your key

Launched Long-term version stability policy: /v5 stays additive forever; breaking changes go to a new major (see Versioning)

Added Bearer-token authentication on every /v5 endpoint: Authorization: Bearer {key} or ?api-key= for browser-side testing

Added Demo keys: sandbox access that returns sample payloads without burning quota, so the docs and homepage can fire live requests without an account

Changed Monthly request limits moved from a hard cap to a soft cap: email alerts at 50 / 80 / 100% and a grace period before 403s start (see Monthly request limits)

Added ?q=: full-text search across every searchable property, case-insensitive substring match

Added Per-property filter chains with AND-semantics: e.g. ?region=Europe&landlocked=1

Added Aggregate searches: /v5/code?q= spans every code property (alpha_2, alpha_3, ccn3, fips, gec, fifa, cioc); /v5/name?q= spans common, official, native, and alternates

Added limit + offset pagination: 1–100 per page, default 25

Added response_fields: comma-separated dot-path projection for picking exactly the slice of the schema you need, with no field-count cap

Added response_fields_omit: comma-separated blocklist for response shape; complements response_fields for trimming heavy branches like names.translations off otherwise-full payloads

Added pretty: human-readable JSON without re-piping through jq

Added Country dataset: 250+ countries with the 80+ field schema covering names, codes, geography, governance, economy, telecom, calendars, and links

Feb 2026

Started REST Countries v5 development began