mirror of
https://gitlab.com/restcountries/restcountries.git
synced 2026-03-31 15:07:46 +01:00
Alejandro Matos
420 lines
9.4 KiB
Markdown
420 lines
9.4 KiB
Markdown
# 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 About Version 2
|
|
The structure has been reverted to its original form from the [Original Project] to maintain compatibility.
|
|
|
|
# REST Countries
|
|
You can access API through https://restcountries.com/v3.1/all
|
|
|
|
|
|
# Contributing
|
|
Any help is welcome! Just edit the file relevant file and create a new Merge Request or you can also
|
|
[donate].
|
|
|
|
# Donations
|
|
We're getting about 1.6 millions hits **each day** and that means also bandwidth (24 GB **per day!**) so
|
|
costs have obviously increased. **Please**, consider making a [donation] to help me pay the server's
|
|
bills, you're welcome to [donate] or you can also
|
|
[buy me a coffee](https://www.buymeacoffee.com/amatos).
|
|
|
|
# Fields
|
|
You can check the [FIELDS.md](FIELDS.md) file to get a description for each field (thanks to @ePascalC!).
|
|
|
|
# Changelog
|
|
### General
|
|
- Netherlands' population fixed
|
|
- Added `fifa` codes
|
|
- Added country's driving side
|
|
- Added country Distinguishing (oval) sign
|
|
### V3
|
|
- Added population
|
|
### V3.1
|
|
#### 19/10
|
|
- Added capital information (lat and long)
|
|
- Added postal code (format and regex)
|
|
#### Previously
|
|
- Added population
|
|
- Added named object for `flags`
|
|
|
|
# API Endpoints
|
|
|
|
Currently there are 3 versions:
|
|
- Version 2 is the original version from restcountries.eu by Fayder Florez
|
|
- Version 3 is the implementation from [this project](https://github.com/mledoze/countries)
|
|
- Version 3.1 adds named values to the `flags` object like this:
|
|
|
|
```json
|
|
"flags": {
|
|
"svg": "https://restcountries.com/data/per.svg",
|
|
"png": "https://restcountries.com/data/png/per.png"
|
|
}
|
|
```
|
|
## 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
|
|
|
|
## All
|
|
|
|
### V2
|
|
``` html
|
|
https://restcountries.com/v2/all
|
|
```
|
|
|
|
### V3.1
|
|
``` html
|
|
https://restcountries.com/v3.1/all
|
|
```
|
|
|
|
|
|
## Name
|
|
|
|
### V2
|
|
Search by country name. It can be the native name or partial name
|
|
|
|
``` javascript
|
|
https://restcountries.com/v2/name/{name}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/name/eesti
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/name/united
|
|
```
|
|
|
|
### V3.1
|
|
Search by country name. It can be the common or official value
|
|
``` html
|
|
https://restcountries.com/v3.1/name/{name}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/name/eesti
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/name/deutschland
|
|
```
|
|
|
|
## Full Name
|
|
### V2
|
|
Search by country's full name
|
|
|
|
``` html
|
|
https://restcountries.com/v2/name/{name}?fullText=true
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/name/aruba?fullText=true
|
|
```
|
|
|
|
### V3.1
|
|
Search by country's full name. It can be the common or official value
|
|
``` html
|
|
https://restcountries.com/v3.1/name/{name}?fullText=true
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/name/aruba?fullText=true
|
|
```
|
|
## Code
|
|
### V2
|
|
Search by ISO 3166-1 2-letter or 3-letter country code
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha/{code}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha/co
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha/col
|
|
```
|
|
### V3.1
|
|
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha/{code}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha/co
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha/col
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha/170
|
|
```
|
|
## List of codes
|
|
### V2
|
|
Search by list of ISO 3166-1 2-letter or 3-letter country codes
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha?codes={code},{code},{code}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha?codes=col,no,ee,pe
|
|
```
|
|
### V3.1
|
|
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha?codes={code},{code},{code}
|
|
```
|
|
|
|
``` html
|
|
https://restcountries.com/v3.1/alpha?codes=170,no,est,pe
|
|
```
|
|
## Currency
|
|
### V2
|
|
Search by ISO 4217 currency code
|
|
|
|
``` html
|
|
https://restcountries.com/v2/currency/{currency}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/currency/cop
|
|
```
|
|
### V3.1
|
|
Search by currency code or name
|
|
``` html
|
|
https://restcountries.com/v3.1/currency/{currency}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/currency/cop
|
|
```
|
|
|
|
### Demonym
|
|
### V3.1
|
|
Now you can search by how a citizen is called.
|
|
``` html
|
|
https://restcountries.com/v3.1/demonym/{demonym}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/demonym/peruvian
|
|
```
|
|
|
|
## Language
|
|
### V2
|
|
Search by ISO 639-1 language code
|
|
|
|
``` javascript
|
|
https://restcountries.com/v2/lang/{et}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/lang/es
|
|
```
|
|
|
|
### V3.1
|
|
Search by language code or name
|
|
``` html
|
|
https://restcountries.com/v3.1/lang/{currency}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/lang/cop
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/lang/spanish
|
|
```
|
|
|
|
## Capital city
|
|
|
|
_This is the same in both versions_
|
|
|
|
Search by capital city
|
|
|
|
``` javascript
|
|
https://restcountries.com/v2/capital/{capital}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/capital/tallinn
|
|
```
|
|
|
|
``` javascript
|
|
https://restcountries.com/v3.1/capital/{capital}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/capital/tallinn
|
|
```
|
|
|
|
## Calling code
|
|
### V2
|
|
Search by calling code
|
|
|
|
``` html
|
|
https://restcountries.com/v2/callingcode/{callingcode}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/callingcode/372
|
|
```
|
|
### V3.1
|
|
In version 3, calling codes are in the _idd_ object. There is no implementation
|
|
to search by calling codes in V3.
|
|
|
|
## Region
|
|
### V2 - V3 & V3.1
|
|
Search by region (replace X with the version you want to use)
|
|
|
|
``` html
|
|
https://restcountries.com/vX/region/{region}
|
|
```
|
|
``` html
|
|
https://restcountries.com/vX/region/europe
|
|
```
|
|
## Subregions
|
|
### V2 - V3 & V3.1
|
|
You can search by subregions (replace X with the version you want to use)
|
|
``` html
|
|
https://restcountries.com/vX/subregion/{subregion}
|
|
```
|
|
``` html
|
|
https://restcountries.com/vX/subregion/Northern Europe
|
|
```
|
|
|
|
## Regional Bloc (*Version 2 only*)
|
|
|
|
Search by regional bloc:
|
|
|
|
- EU (European Union)
|
|
- EFTA (European Free Trade Association)
|
|
- CARICOM (Caribbean Community)
|
|
- PA (Pacific Alliance)
|
|
- AU (African Union)
|
|
- USAN (Union of South American Nations)
|
|
- EEU (Eurasian Economic Union)
|
|
- AL (Arab League)
|
|
- ASEAN (Association of Southeast Asian Nations)
|
|
- CAIS (Central American Integration System)
|
|
- CEFTA (Central European Free Trade Agreement)
|
|
- NAFTA (North American Free Trade Agreement)
|
|
- SAARC (South Asian Association for Regional Cooperation)
|
|
|
|
``` html
|
|
https://restcountries.com/v2/regionalbloc/{regionalbloc}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/regionalbloc/eu
|
|
```
|
|
|
|
## Translation (*V3.x only*)
|
|
You can search by any translation name
|
|
``` html
|
|
https://restcountries.com/v3.1/translation/{translation}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/translation/germany
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/translation/alemania
|
|
```
|
|
``` html
|
|
https://restcountries.com/v3.1/translation/Saksamaa
|
|
```
|
|
|
|
## Response Example
|
|
|
|
``` html
|
|
https://restcountries.com/v2/alpha/col
|
|
```
|
|
|
|
``` json
|
|
[[{
|
|
"name": "Colombia",
|
|
"topLevelDomain": [".co"],
|
|
"alpha2Code": "CO",
|
|
"alpha3Code": "COL",
|
|
"callingCodes": ["57"],
|
|
"capital": "Bogotá",
|
|
"altSpellings": ["CO", "Republic of Colombia", "República de Colombia"],
|
|
"region": "Americas",
|
|
"subregion": "South America",
|
|
"population": 48759958,
|
|
"latlng": [4.0, -72.0],
|
|
"demonym": "Colombian",
|
|
"area": 1141748.0,
|
|
"gini": 55.9,
|
|
"timezones": ["UTC-05:00"],
|
|
"borders": ["BRA", "ECU", "PAN", "PER", "VEN"],
|
|
"nativeName": "Colombia",
|
|
"numericCode": "170",
|
|
"currencies": [{
|
|
"code": "COP",
|
|
"name": "Colombian peso",
|
|
"symbol": "$"
|
|
}],
|
|
"languages": [{
|
|
"iso639_1": "es",
|
|
"iso639_2": "spa",
|
|
"name": "Spanish",
|
|
"nativeName": "Español"
|
|
}],
|
|
"translations": {
|
|
"de": "Kolumbien",
|
|
"es": "Colombia",
|
|
"fr": "Colombie",
|
|
"ja": "コロンビア",
|
|
"it": "Colombia",
|
|
"br": "Colômbia",
|
|
"pt": "Colômbia"
|
|
},
|
|
"flag": "https://restcountries.com/data/col.svg",
|
|
"regionalBlocs": [{
|
|
"acronym": "PA",
|
|
"name": "Pacific Alliance",
|
|
"otherAcronyms": [],
|
|
"otherNames": ["Alianza del Pacífico"]
|
|
}, {
|
|
"acronym": "USAN",
|
|
"name": "Union of South American Nations",
|
|
"otherAcronyms": ["UNASUR", "UNASUL", "UZAN"],
|
|
"otherNames": ["Unión de Naciones Suramericanas", "União de Nações Sul-Americanas", "Unie van Zuid-Amerikaanse Naties", "South American Union"]
|
|
}]
|
|
}]
|
|
```
|
|
|
|
## Filter Response
|
|
|
|
You can filter the output of your request to include only the specified fields.
|
|
|
|
``` javascript
|
|
https://restcountries.com/v2/{service}?fields={field},{field},{field}
|
|
```
|
|
``` html
|
|
https://restcountries.com/v2/all?fields=name,capital,currencies
|
|
```
|
|
|
|
## Similar projects
|
|
* [REST Countries] (original project)
|
|
* [Countries of the world]
|
|
* [REST Countries Node.js]
|
|
* [REST Countries Ruby]
|
|
* [REST Countries Go]
|
|
* [REST Countries Python]
|
|
* [world-currencies]
|
|
|
|
[world-currencies]: https://github.com/wiredmax/world-currencies
|
|
[REST Countries Node.js]: https://github.com/aredo/restcountries
|
|
[REST Countries Ruby]: https://github.com/davidesantangelo/restcountry
|
|
[REST Countries Go]: https://github.com/alediaferia/gocountries
|
|
[REST Countries Python]: https://github.com/SteinRobert/python-restcountries
|
|
[Countries of the world]: http://countries.petethompson.net
|
|
[REST Countries]: https://github.com/apilayer/restcountries
|
|
[Original Project]: https://github.com/apilayer/restcountries/
|
|
[donation]: https://www.paypal.me/amatosg/15
|
|
[donate]: https://www.paypal.me/amatosg/15
|