API Reference
Restful Countries API allows users to explore the entire database for information on
countries and their states, presidents, flag, population, covid19 stats and others.
Restful Countries API is organized around REST. Our API has predictable resource-oriented URLs,
returns JSON-encoded responses and uses standard HTTP response codes, and verbs.
Authentication Guide
Restful Countries API requires authentication credentials, in the form of an API key, to
be sent with each request.
To obtain an API key, go to the request
access token page and register your application by providing your email and
application URL. This will allocate a unique key to your application which can be sent
with any GET request for a public resource served by Restful Countries API.
Rate Limiting
Rate limiting is applied to the Restful Countries API to ensure a high-quality service
is delivered for all users, and to protect client applications from unexpected loops.
Per application rates
You can make up to 100 requests within a minute period. If you exceed this limit, you
will receive a 429 Too Many Requests HTTP status code for each
request made within the remainder of the one-minute window. At the end of the period,
your rate limit will reset back to its maximum value of 100 requests.
Increasing your rate limit
If you have an application that requires a higher rate limit than the default applied,
then please contact us , we will be happy to help.
Base URL
GET https://restfulcountries.com/api/v1
All Countries
GET https://restfulcountries.com/api/v1/countries
Returns information of all the countries available in the world. Including every other
information on that country.
Parameters
Path Parameters
Path parameter |
Description |
None |
None |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
per_page |
optional |
Specifies number of items to return. Returns paginated data |
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?per_page=1" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by name
GET https://restfulcountries.com
/api/v1/countries/{country}
Returns information of a particular country.
Parameters
Path Parameters
Path parameter |
Description |
{country} |
The name of the particular country you want to look up. Example
https://restfulcountries.com
/api/v1/countries/Nigeria
|
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
none |
none |
none |
none |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/Nigeria" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
You may use space in country name or hyphen e.g
countries/south africa
or countries/south-africa
Country by continent
GET https://restfulcountries.com
/api/v1/countries?continent={continent}
Returns information of all countries in a continent.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
continent |
required |
Specifies continent to retrieve data on. Example
https://restfulcountries.com
/api/v1/countries?continent=africa
|
String |
per_page |
optional |
Specifies number of items to return. Returns paginated data. Example
https://restfulcountries.com
/api/v1/countries?continent=africa&per_page=5
|
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?continent=africa" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by Population
GET https://restfulcountries.com
/api/v1/countries?population_from={min_population}&population_to={max_population}
Returns information a list of countries filtered by their Population range.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
population_from |
optional |
Specifies countries population starting point i.e. smallest population.
Example
https://restfulcountries.com
/api/v1/countries?population_from=500000
|
integer |
population_to |
optional |
Specifies countries population ending point i.e. largest population..
Example
https://restfulcountries.com
/api/v1/countries?population_to=1000000
|
integer |
per_page |
optional |
Specifies number of items to return. Returns paginated data. Example
https://restfulcountries.com
/api/v1/countries?continent=africa&per_page=5
|
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?population_from=20000&population_to=5000000" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by Size
GET
https://restfulcountries.com
/api/v1/countries?size_from={min_size}&size_to={max_size}
Returns information a list of countries filtered by size (kmĀ²) range .
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
size_from |
optional |
Specifies countries size starting point i.e. smallest size.
Example
https://restfulcountries.com
/api/v1/countries?size_from=10000
|
integer |
size_to |
optional |
Specifies countries population ending point i.e. largest size..
Example
https://restfulcountries.com
/api/v1/countries?size_to=1000000
|
integer |
per_page |
optional |
Specifies number of items to return. Returns paginated data. Example
https://restfulcountries.com
/api/v1/countries?size_from=10000&size_to=100000&per_page=5
|
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?size_from=300&size_to=200000" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by ISO2
GET
https://restfulcountries.com/api/v1/countries?iso2={iso2}
Returns information of a country by ISO2 code .
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
iso2 |
optional |
Specifies country to retrieve by passing country's ISO2 code.
Example
https://restfulcountries.com
/api/v1/countries?iso2=AO
|
String |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?iso2=GH" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by ISO3 - GET
GET
https://restfulcountries.com/api/v1/countries?iso3={iso3}
Returns information of a country by ISO3 code .
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
iso3 |
optional |
Specifies country to retrieve by passing country's ISO2 code.
Example
https://restfulcountries.com
/api/v1/countries?iso3=AGO
|
String |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?iso3=AGO" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Country by Code
GET https://restfulcountries.com
/api/v1/countries?code={code}
Returns information of a single country by calling code.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
code |
required |
Specifies country to retrieve by passing country's calling code. Example
https://restfulcountries.com
/api/v1/countries?code=234
|
String |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries?code=234" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Sample Response
Slim Country Response
GET https://restfulcountries.com
/api/v1/countries?fetch_type=slim
Returns minimal information of countries. Response will only include name, phone code,
flag and self link
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
fetch_type |
required |
Specifies that response should only include name, phone code,
flag and self link . Example
https://restfulcountries.com
/api/v1/countries?fetch_type=slim
|
String |
Sample Request
curl -I -X "Accept: application/json" "Authorization: Bearer ${TOKEN}" GET "https://restfulcountries.com
/api/v1/countries?per_page=20"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Presidents by Country
GET https://restfulcountries.com/api/v1/countries/{country}/presidents
Returns information on a country's past and present presidents and/or presidents
Parameters
Path Parameters
Path parameter |
Description |
{country} |
Specifies the country the name of the particular country you want to look up. Example
https://restfulcountries.com
/api/v1/countries/india/presidents
|
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
none |
none |
none |
none |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/nigeria/presidents" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Presidents by Country and Name
GET https://restfulcountries.com/api/v1/countries/{country}/presidents/{president}
Returns information on a particular country's presidents including leader's name, gender, appointment start and end date.
Parameters
Path Parameters
Path parameter |
Description |
{country} |
Specifies the country the name of the particular country you want to look up. Example
https://restfulcountries.com/api/v1/countries/india/presidents/{president}
|
{president} |
Specifies the president in the {country} you want to look up. Example
https://restfulcountries.com/api/v1/countries/{country}/presidents/Ashraf Ghani
|
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
none |
none |
none |
none |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/nigeria/presidents/Muhammadu Buhari" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Covid 19 Cases Only
GET https://restfulcountries.com/api/v1/covid19
Returns countries information on Covid19 cases.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
per_page |
optional |
Specifies number of items to return. Returns paginated data |
integer |
Sample Request
curl -I -X "Accept: application/json" "Authorization: Bearer ${TOKEN}" GET "https://restfulcountries.com
/api/v1/countries?per_page=1"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Covid 19 cases by death range only
GET https://restfulcountries.com
/api/v1/covid19?death_from={minimum_death}&death_to={maximum-deaths}
Returns information countries Covid19 cases filtered by death rate.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
death_from |
optional |
Specifies countries covid19 death rate starting point i.e. lowest death rate.
Example
https://restfulcountries.com
/api/v1/covid19?death_from=10000
|
integer |
death_to |
optional |
Specifies countries covid19 death rate ending point i.e. highest death rate.
Example
https://restfulcountries.com
/api/v1/covid19?death_to=50000
|
integer |
per_page |
optional |
Specifies number of items to return. Returns paginated data |
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/covid19?death_from=1000&death_to1000000" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Sample Response
Covid 19 cases by total confirmed range only
GET https://restfulcountries.com
/api/v1/covid19?total_from={minimum_total}&death_to={maximum-total}
Returns information countries Covid19 cases filtered by total confirmed cases.
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
total_from |
optional |
Specifies countries covid19 death rate starting point i.e. lowest death rate.
Example
https://restfulcountries.com/api/v1/covid19?total_from=3000
|
integer |
total_to |
optional |
Specifies countries covid19 death rate ending point i.e. highest death rate.
Example
https://restfulcountries.com/api/v1/covid19?total_to=500000
|
integer |
per_page |
optional |
Specifies number of items to return. Returns paginated data |
integer |
Sample Request
curl -I "https://restfulcountries.com/api/v1/covid19?total_from=2000&total_to=10000000" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Sample Response
State by Country Name
GET https://restfulcountries.com/api/v1/countries/{country}/states
Returns information a country's states.
Parameters
Path Parameters
Path parameter |
Description |
{country} |
Specifies the country the name of the particular country you want to look up. Example
https://restfulcountries.com/api/v1/countries/Nigeria/states
|
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
none |
none |
none |
none |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/Nigeria/states" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
State by Country Name and State Name
GET https://restfulcountries.com/api/v1/countries/{country}/states/{state}
Returns information a country's states.
Parameters
Path Parameters
Path parameter |
Description |
{country} |
Specifies the country the name of the particular country you want to look up. Example
https://restfulcountries.com/api/v1/countries/United States/states/{state}
|
{state} |
Specifies the state of the particular {country} you want to look up. Example
https://restfulcountries.com/api/v1/countries/{country}/states/Alaska
|
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
none |
none |
none |
none |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/united-states/states/Alaska" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
Sample Response
Slim State Response
GET https://restfulcountries.com/api/v1/countries/United-States/states?fetch_type=slim
Returns minimal information of country's state. Response will only include name, phone code,
flag and self link
Parameters
Path Parameters
Path parameter |
Description |
none |
none |
Query string parameter
Query string parameter |
Required / optional |
Description |
Type |
fetch_type |
required |
Specifies that response should only include name, ISO 2 code, ISO 3 code and self link. Example
https://restfulcountries.com/api/v1/countries/United-States/states?fetch_type=slim
|
String |
Sample Request
curl -I "https://restfulcountries.com/api/v1/countries/united-states/states?fetch_type=slim" -H "Accept: application/json" -H "Authorization: Bearer {TOKEN}"
In the sample request above, replace {TOKEN} with your actual token. Generate your Token here
References
As much as we try to source data from reliable sources, the information
returned by
our api stands to be corrected in the case of spelling errors or invalid data.
Please visit our Feedback page to let us know your complaints or suggestions for new features.