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.
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 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.
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.
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.
Returns information of all the countries available in the world. Including every other information on that country.
| Path parameter | Description |
|---|---|
| None | None |
| Query string parameter | Required / optional | Description | Type |
|---|---|---|---|
| per_page | optional | Specifies number of items to return. Returns paginated data |
integer |
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
Returns information of a particular country.
| 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 | Required / optional | Description | Type |
|---|---|---|---|
| none | none | none | none |
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
Returns information of all countries in a continent.
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information a list of countries filtered by their Population range.
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information a list of countries filtered by size (km²) range .
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information of a country by ISO2 code .
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information of a country by ISO3 code .
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information of a single country by calling code.
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns minimal information of countries. Response will only include name, phone code, flag and self link
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information on a country's past and present presidents and/or presidents
| 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 | Required / optional | Description | Type |
|---|---|---|---|
| none | none | none | none |
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
Returns information on a particular country's presidents including leader's name, gender, appointment start and end date.
| 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 | Required / optional | Description | Type |
|---|---|---|---|
| none | none | none | none |
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
Returns countries information on Covid19 cases.
| Path parameter | Description |
|---|---|
| none | none |
| Query string parameter | Required / optional | Description | Type |
|---|---|---|---|
| per_page | optional | Specifies number of items to return. Returns paginated data |
integer |
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
Returns information countries Covid19 cases filtered by death rate.
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information countries Covid19 cases filtered by total confirmed cases.
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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
Returns information a country's states.
| 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 | Required / optional | Description | Type |
|---|---|---|---|
| none | none | none | none |
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
Returns information a country's states.
| 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 | Required / optional | Description | Type |
|---|---|---|---|
| none | none | none | none |
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
Returns minimal information of country's state. Response will only include name, phone code, flag and self link
| Path parameter | Description |
|---|---|
| none | none |
| 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 |
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