Alejandro Matos
9.3 KiB
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 always welcome! Just edit the relevant file and create a new Merge Request or you can also donate using Patreon or PayPal.
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!).
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
- Version 3.1 adds named values to the
flagsobject like this:
"flags": {
"svg": "https://restcountries.com/data/per.svg",
"png": "https://restcountries.com/data/png/per.png"
}
Using this Project
#Endpoints Below are described the REST endpoints available that you can use to search for countries
All
V2
https://restcountries.com/v2/all
V3.1
https://restcountries.com/v3.1/all
Name
V2
Search by country name. It can be the native name or partial name
https://restcountries.com/v2/name/{name}
https://restcountries.com/v2/name/eesti
https://restcountries.com/v2/name/united
V3.1
Search by country name. 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
V2
Search by country's full name
https://restcountries.com/v2/name/{name}?fullText=true
https://restcountries.com/v2/name/aruba?fullText=true
V3.1
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
V2
Search by ISO 3166-1 2-letter or 3-letter country code
https://restcountries.com/v2/alpha/{code}
https://restcountries.com/v2/alpha/co
https://restcountries.com/v2/alpha/col
V3.1
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
V2
Search by list of ISO 3166-1 2-letter or 3-letter country codes
https://restcountries.com/v2/alpha?codes={code},{code},{code}
https://restcountries.com/v2/alpha?codes=col,no,ee,pe
V3.1
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
V2
Search by ISO 4217 currency code
https://restcountries.com/v2/currency/{currency}
https://restcountries.com/v2/currency/cop
V3.1
Search by currency code or name
https://restcountries.com/v3.1/currency/{currency}
https://restcountries.com/v3.1/currency/cop
Demonym
V3.1
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
V2
Search by ISO 639-1 language code
https://restcountries.com/v2/lang/{et}
https://restcountries.com/v2/lang/es
V3.1
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
This is the same in both versions
Search by capital city
https://restcountries.com/v2/capital/{capital}
https://restcountries.com/v2/capital/tallinn
https://restcountries.com/v3.1/capital/{capital}
https://restcountries.com/v3.1/capital/tallinn
Calling code
V2
Search by calling code
https://restcountries.com/v2/callingcode/{callingcode}
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)
https://restcountries.com/vX/region/{region}
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)
https://restcountries.com/vX/subregion/{subregion}
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)
https://restcountries.com/v2/regionalbloc/{regionalbloc}
https://restcountries.com/v2/regionalbloc/eu
Translation (V3.x only)
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
Response Example
https://restcountries.com/v2/alpha/col
[[{
"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.
https://restcountries.com/v2/{service}?fields={field},{field},{field}
https://restcountries.com/v2/all?fields=name,capital,currencies