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 http://127.0.0.1:8000/api/v1

All Countries

GET http://127.0.0.1:8000/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 "http://127.0.0.1:8000/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

Sample Response

                            

Country by name

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries/Nigeria
Query string parameter
Query string parameter Required / optional Description Type
none none none none
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response

                            
You may use space in country name or hyphen e.g countries/south africa or countries/south-africa

Country by continent

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries?continent=africa
String
per_page optional Specifies number of items to return. Returns paginated data. Example
http://127.0.0.1:8000 /api/v1/countries?continent=africa&per_page=5
integer
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response

                            

Country by Population

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries?population_from=500000
integer
population_to optional Specifies countries population ending point i.e. largest population.. Example
http://127.0.0.1:8000 /api/v1/countries?population_to=1000000
integer
per_page optional Specifies number of items to return. Returns paginated data. Example
http://127.0.0.1:8000 /api/v1/countries?continent=africa&per_page=5
integer
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

Country by Size

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries?size_from=10000
integer
size_to optional Specifies countries population ending point i.e. largest size.. Example
http://127.0.0.1:8000 /api/v1/countries?size_to=1000000
integer
per_page optional Specifies number of items to return. Returns paginated data. Example
http://127.0.0.1:8000 /api/v1/countries?size_from=10000&size_to=100000&per_page=5
integer
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

Country by ISO2

GET http://127.0.0.1:8000/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
http://127.0.0.1:8000 /api/v1/countries?iso2=AO
String
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

Country by ISO3 - GET

GET http://127.0.0.1:8000/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
http://127.0.0.1:8000 /api/v1/countries?iso3=AGO
String
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

Country by Code

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries?code=234
String
Sample Request
curl -I "http://127.0.0.1:8000/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 http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/countries?fetch_type=slim
String
Sample Request
curl -I -X "Accept: application/json" "Authorization: Bearer ${TOKEN}" GET "http://127.0.0.1:8000
                                    /api/v1/countries?per_page=20"

In the sample request above, replace {TOKEN} with your actual token. Generate your Token here

Sample Response



                            

Presidents by Country

GET http://127.0.0.1:8000/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
http://127.0.0.1:8000 /api/v1/countries/india/presidents
Query string parameter
Query string parameter Required / optional Description Type
none none none none
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

Presidents by Country and Name

GET http://127.0.0.1:8000/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
http://127.0.0.1:8000/api/v1/countries/india/presidents/{president}
{president} Specifies the president in the {country} you want to look up. Example
http://127.0.0.1:8000/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 "http://127.0.0.1:8000/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

Sample Response


                            

Covid 19 Cases Only

GET http://127.0.0.1:8000/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 "http://127.0.0.1:8000
                                    /api/v1/countries?per_page=1"

In the sample request above, replace {TOKEN} with your actual token. Generate your Token here

Sample Response



                            

Covid 19 cases by death range only

GET http://127.0.0.1:8000 /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
http://127.0.0.1:8000 /api/v1/covid19?death_from=10000
integer
death_to optional Specifies countries covid19 death rate ending point i.e. highest death rate. Example
http://127.0.0.1:8000 /api/v1/covid19?death_to=50000
integer
per_page optional Specifies number of items to return.
Returns paginated data
integer
Sample Request
curl -I "http://127.0.0.1:8000/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 http://127.0.0.1:8000 /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
http://127.0.0.1:8000/api/v1/covid19?total_from=3000
integer
total_to optional Specifies countries covid19 death rate ending point i.e. highest death rate. Example
http://127.0.0.1:8000/api/v1/covid19?total_to=500000
integer
per_page optional Specifies number of items to return.
Returns paginated data
integer
Sample Request
curl -I "http://127.0.0.1:8000/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 http://127.0.0.1:8000/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
http://127.0.0.1:8000/api/v1/countries/Nigeria/states
Query string parameter
Query string parameter Required / optional Description Type
none none none none
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

State by Country Name and State Name

GET http://127.0.0.1:8000/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
http://127.0.0.1:8000/api/v1/countries/United States/states/{state}
{state} Specifies the state of the particular {country} you want to look up. Example
http://127.0.0.1:8000/api/v1/countries/{country}/states/Alaska
Query string parameter
Query string parameter Required / optional Description Type
none none none none
Sample Request
curl -I "http://127.0.0.1:8000/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 http://127.0.0.1:8000/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
http://127.0.0.1:8000/api/v1/countries/United-States/states?fetch_type=slim
String
Sample Request
curl -I "http://127.0.0.1:8000/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

Sample Response



                            

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.