diff --git a/README.md b/README.md index cc78e68..5b0421d 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,258 @@ +> **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 + +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 + +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, + +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 +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. +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](https://github.com/yusifaliyevpro/countries) +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` | `List<{lang, official, common}>` | +| `languages` | `Map` | `List<{iso639_1, iso639_2, name, nativeName}>` | +| `currencies` | `Map` | `List<{code, name, symbol}>` | +| `translations` | `Map` | `List<{lang, official, common}>` | +| `demonyms` | `Map` | `List<{lang, male, female}>` | +| `gini` | `Map` | `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).