Alejandro Matos
9.1 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 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.
#Fields You can check the FIELDS.md file to get a description for each field (thanks to @ePascalC!).
Changelog
General
- Netherlands' population fixed
V3
- Added population
V3.1
- 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
- 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"
}
Below are described the REST endpoints available that you can use to search for countries
All
V2
https://restcountries.com/v2/all
V3
https://restcountries.com/v3/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
Search by country name. It can be the common or official value
https://restcountries.com/v3/name/{name}
https://restcountries.com/v3/name/eesti
https://restcountries.com/v3/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
Search by country's full name. It can be the common or official value
https://restcountries.com/v3/name/{name}?fullText=true
https://restcountries.com/v3/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
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
https://restcountries.com/v3/alpha/{code}
https://restcountries.com/v3/alpha/co
https://restcountries.com/v3/alpha/col
https://restcountries.com/v3/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
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
https://restcountries.com/v3/alpha?codes={code},{code},{code}
https://restcountries.com/v3/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
Search by currency code or name
https://restcountries.com/v3/currency/{currency}
https://restcountries.com/v3/currency/cop
Demonym
V3
Now you can search by how a citizen is called.
https://restcountries.com/v3/demonym/{demonym}
https://restcountries.com/v3/demonym/peruvian
Language
V2
Search by ISO 639-1 language code
https://restcountries.com/v2/lang/{et}
https://restcountries.com/v2/lang/es
V3
Search by language code or name
https://restcountries.com/v3/lang/{currency}
https://restcountries.com/v3/lang/cop
https://restcountries.com/v3/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/capital/{capital}
https://restcountries.com/v3/capital/tallinn
Calling code
V2
Search by calling code
https://restcountries.com/v2/callingcode/{callingcode}
https://restcountries.com/v2/callingcode/372
V3
In version 3, calling codes are in the idd object. There is no implementation to search by calling codes in V3.
Region
V2
In version 2 regions are continent and subregions are region Search by continent: Africa, Americas, Asia, Europe, Oceania
https://restcountries.com/v2/continent/{continent}
https://restcountries.com/v2/continent/europe
V3
In version 3, continents are Regions and regions are Subregions
https://restcountries.com/v2/region/{region}
https://restcountries.com/v2/region/europe
Subregions
###V3 You can search by subregions
https://restcountries.com/v2/subregion/{subregion}
https://restcountries.com/v2/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
You can search by any translation name
https://restcountries.com/v3/translation/{translation}
https://restcountries.com/v3/translation/germany
https://restcountries.com/v3/translation/alemania
https://restcountries.com/v3/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