v4 Preview — Not for production use REST Countries v4 is currently available as a preview at /v4. It introduces new fields, richer data, and breaking changes from v3.1. The API is still subject to change before its stable release. Do not use it in production yet. Join the discussion and share your feedback at issue #286.

About this Project

This project is inspired on restcountries.eu by Fayder Florez. Although the original project has now moved to a subscription base API, this project is still Open Source and Free to use.

REST Countries

You can access API through https://restcountries.com/v3.1/all

Contributing

Any help is always welcome! Just edit the relevant file and create a new Merge Request.

Donations

This are getting out of control. As I stated here, the server is not going to hold much longer. I'm getting about 4 million hits each day and that means CPU ussage (99%) and also bandwidth consumption (120 GB per day!) so costs have obviously increased. Please, consider making a donation on Patreon or PayPal. This will help me pay the server's bills

Fields

You can check the FIELDS.md file to get a description for each field (thanks to @ePascalC!). This file might be outdated and will not be updated.

API Endpoints

Endpoints

Below are described the REST endpoints available that you can use to search for countries

Latest added Endpoint

Independent

Now you can get all independent (or not independent) countries by calling this endpoint:

https://restcountries.com/v3.1/independent?status=true

If you don't specify the status, true will be taken as default. You can mix it with the fields filter like this:

https://restcountries.com/v3.1/independent?status=true&fields=languages,capital

All

You must specify the fields you need (up to 10 fields) when calling the all endpoints, otherwise you'll get a bad request response. Please see this issue for more information. This applies to all versions.

https://restcountries.com/v3.1/all

Name

Search by country name. If you want to get an exact match, use the next endpoint. It can be the common or official value

https://restcountries.com/v3.1/name/{name}

https://restcountries.com/v3.1/name/eesti

https://restcountries.com/v3.1/name/deutschland

Full Name

Search by country's full name. It can be the common or official value

https://restcountries.com/v3.1/name/{name}?fullText=true

https://restcountries.com/v3.1/name/aruba?fullText=true

Code

Search by cca2, ccn3, cca3 or cioc country code (yes, any!)

https://restcountries.com/v3.1/alpha/{code}

https://restcountries.com/v3.1/alpha/co

https://restcountries.com/v3.1/alpha/col

https://restcountries.com/v3.1/alpha/170

List of codes

Search by cca2, ccn3, cca3 or cioc country code (yes, any!)

https://restcountries.com/v3.1/alpha?codes={code},{code},{code}

https://restcountries.com/v3.1/alpha?codes=170,no,est,pe

Currency

Search by currency code or name

https://restcountries.com/v3.1/currency/{currency}

https://restcountries.com/v3.1/currency/cop

Demonym

Now you can search by how a citizen is called.

https://restcountries.com/v3.1/demonym/{demonym}

https://restcountries.com/v3.1/demonym/peruvian

Language

Search by language code or name

https://restcountries.com/v3.1/lang/{currency}

https://restcountries.com/v3.1/lang/cop

https://restcountries.com/v3.1/lang/spanish

Capital city

Search by capital city

https://restcountries.com/v3.1/capital/{capital}

https://restcountries.com/v3.1/capital/tallinn

Calling code

In version 3, calling codes are in the idd object. There is no implementation to search by calling codes in V3.

Region

Search by region

https://restcountries.com/v3.1/region/{region}

https://restcountries.com/v3.1/region/europe

Subregions

You can search by subregions

https://restcountries.com/v3.1/subregion/{subregion}

https://restcountries.com/v3.1/subregion/Northern Europe

Translation

You can search by any translation name

https://restcountries.com/v3.1/translation/{translation}

https://restcountries.com/v3.1/translation/germany

https://restcountries.com/v3.1/translation/alemania

https://restcountries.com/v3.1/translation/saksamaa

Filter Response

You can filter the output of your request to include only the specified fields.

https://restcountries.com/v3.1/{endpoint}?fields={field},{field},{field}

https://restcountries.com/v3.1/all?fields=name,capital,currencies

REST Countries Typed API Package

Yusif Aliyev from Azerbaijan created an npm package which provides TypeScript support for the REST Countries API. Everyone can use the package for their own purpose. This package offers full type and autocomplete support for anyone using JavaScript or TypeScript. Users no longer need to spend time reading documentation or manually writing API URLs and types. You can easily use all the package's functionalities by calling its functions. He is also open to contributing further improvements.

You can find the code here

Similar projects

• REST Countries (original project)
• Countries of the world
• REST Countries Node.js
• REST Countries Ruby
• REST Countries Go
• REST Countries Python
• REST Countries Java
• world-currencies

---

Migrating from v3.1 to v4

The v4 API is available at https://restcountries.com/v4/. Below are the changes you need to account for when upgrading from v3.1.

Base URL

# v3.1
https://restcountries.com/v3.1/{endpoint}

# v4
https://restcountries.com/v4/{endpoint}

Fields with breaking shape changes

These fields exist in both versions but have a different structure in v4:

Field	v3.1 shape	v4 shape
name.nativeName	Map<langCode, {official, common}>	List<{lang, official, common}>
languages	Map<iso639_2, languageName>	List<{iso639_1, iso639_2, name, nativeName}>
currencies	Map<currencyCode, {name, symbol}>	List<{code, name, symbol}>
translations	Map<langCode, {official, common}>	List<{lang, official, common}>
demonyms	Map<lang, {m, f}>	List<{lang, male, female}>
gini	Map<year, value>	List<{year, value}>

Removed fields

Field	Replacement
latlng	Use geolocation ({latitude, longitude})
flags (object with svg/png/alt)	Merged into flag — see below
flag (emoji string)	Moved inside the flag object as flag.emoji

flag / flags consolidation

In v3.1 there were two separate fields. In v4 they are a single flag object:

// v3.1
"flag": "🇦🇼",
"flags": { "svg": "...", "png": "...", "alt": "..." }

// v4
"flag": { "svg": "...", "png": "...", "alt": "...", "emoji": "🇦🇼" }

New fields in v4

Field	Description
callingCodes	Complete calling codes as a flat string list (e.g. ["297"])
geolocation	Named {latitude, longitude} object replacing the latlng array
sovereignState	cca3 of the governing sovereign state; "" for independent countries
regionalBlocs	Regional/trade bloc memberships
religion	Religious group breakdown with population and percentage
ethnicity	Ethnic group breakdown with percentage
government	Government type and current leaders
density	Population density in people/km²
gdp	GDP total and per-capita in USD
hdi	Human Development Index score (0.0–1.0)
nationalHoliday	National/independence day date string
anthem	Name of the national anthem

For the full field reference see FIELDS_V4.md.