update README with information about v4

description about the difference between v3 and v4, things to be aware of when migrating
2026-03-31 15:07:46 +01:00 · 2026-02-26 01:50:45 -05:00
parent 8f76f06d98
commit 7026740ccd
1 changed files with 178 additions and 73 deletions
@@ -1,203 +1,237 @@
+> **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](https://gitlab.com/restcountries/restcountries/-/issues/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.

-## Important Information
-* The structure of V2 has been reverted to its original form from the [Original Project] to maintain compatibility.
-* ***Only the latest version will receive updates and improvements.***
-
 # 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 or you can also 
-donate using [Patreon](https://www.patreon.com/amatos) or [PayPal](https://www.paypal.me/amatosg/15).
+
+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](https://gitlab.com/restcountries/restcountries/-/issues/187), 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](https://www.patreon.com/amatos) or [PayPal](https://www.paypal.me/amatosg/15). This will help me pay the server's bills

 # Fields
-You can check the [FIELDS.md](FIELDS.md) file to get a description for each field (thanks to @ePascalC!).
+
+You can check the [FIELDS.md](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

-## Using this Project
-
- [Famosos](https://famosos.com)
- [Cultural Care](https://www.culturalcare.world/)
- [Covidata](https://worldcovidata.com/)
- [Asendia](https://tracking.asendia.com)
- [Picker](https://mwb.pickerexpress.com/#/login)
-
 # 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:
-``` html
+
+```html
 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:

-``` html
+```html
 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](https://gitlab.com/restcountries/restcountries/-/issues/265)
 for more information. This applies to all versions.
-``` html
+
+```html
 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
-``` html
+
+```html
 https://restcountries.com/v3.1/name/{name}
 ```

-``` html
+```html
 https://restcountries.com/v3.1/name/eesti
 ```

-``` html
+```html
 https://restcountries.com/v3.1/name/deutschland
 ```

 ## Full Name

 Search by country's full name. It can be the common or official value
-``` html
+
+```html
 https://restcountries.com/v3.1/name/{name}?fullText=true
 ```

-``` html
+```html
 https://restcountries.com/v3.1/name/aruba?fullText=true
 ```
+
 ## Code

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

-``` html
+```html
 https://restcountries.com/v3.1/alpha/{code}
 ```

-``` html
+```html
 https://restcountries.com/v3.1/alpha/co
 ```

-``` html
+```html
 https://restcountries.com/v3.1/alpha/col
 ```

-``` html
+```html
 https://restcountries.com/v3.1/alpha/170
 ```
+
 ## List of codes

 Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
-``` html
+
+```html
 https://restcountries.com/v3.1/alpha?codes={code},{code},{code}
 ```

-``` html
+```html
 https://restcountries.com/v3.1/alpha?codes=170,no,est,pe
 ```
+
 ## Currency

 Search by currency code or name
-``` html
+
+```html
 https://restcountries.com/v3.1/currency/{currency}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/currency/cop
 ```

 ## Demonym
+
 Now you can search by how a citizen is called.
-``` html
+
+```html
 https://restcountries.com/v3.1/demonym/{demonym}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/demonym/peruvian
 ```

 ## Language
+
 Search by language code or name
-``` html
+
+```html
 https://restcountries.com/v3.1/lang/{currency}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/lang/cop
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/lang/spanish
 ```

 ## Capital city
+
 Search by capital city

-``` html
+```html
 https://restcountries.com/v3.1/capital/{capital}
 ```
-``` html
+
+```html
 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.
+
+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 (replace X with the version you want to use)

-``` html
+Search by region
+
+```html
 https://restcountries.com/v3.1/region/{region}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/region/europe
 ```
+
 ## Subregions
-You can search by subregions (replace X with the version you want to use)
-``` html
+
+You can search by subregions
+
+```html
 https://restcountries.com/v3.1/subregion/{subregion}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/subregion/Northern Europe
 ```

 ## Translation
+
 You can search by any translation name
-``` html
+
+```html
 https://restcountries.com/v3.1/translation/{translation}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/translation/germany
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/translation/alemania
 ```
-``` html
-https://restcountries.com/v3.1/translation/Saksamaa
+
+```html
+https://restcountries.com/v3.1/translation/saksamaa
 ```

 ## Filter Response

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

-``` html
-https://restcountries.com/v3.1/{service}?fields={field},{field},{field}
+```html
+https://restcountries.com/v3.1/{endpoint}?fields={field},{field},{field}
 ```
-``` html
+
+```html
 https://restcountries.com/v3.1/all?fields=name,capital,currencies
 ```
+
 ## REST Countries Typed API Package
+
 Yusif Aliyev from Azerbaijan created [an npm package](https://www.npmjs.com/package/@yusifaliyevpro/countries)
 which provides TypeScript support for the REST Countries API. Everyone can use
 the package for their own purpose.
@@ -210,14 +244,15 @@ He is also open to contributing further improvements.
 You can find the code [here](https://github.com/yusifaliyevpro/countries)

 ## 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]
+
+- [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]

 [world-currencies]: https://github.com/wiredmax/world-currencies
 [REST Countries Node.js]: https://github.com/aredo/restcountries
@@ -231,3 +266,73 @@ You can find the code [here](https://github.com/yusifaliyevpro/countries)
 [donation]: https://www.paypal.me/amatosg/15
 [donate]: https://www.paypal.me/amatosg/15
 [REST Countries Java]: https://github.com/awais2075/restcountries
+
+---
+
+# 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:
+
+```json
+// 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](FIELDS_V4.md).