Can I use the Country API for commercial purposes?

Yes, but you must have a premium subscription. Commercial use of the Country API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

How do I get an API key and start using the Country API?

Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

What happens if I exceed my quota for the month?

Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page .

What happens if a request to the Country API fails?

The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

What statistics does the Country API return for each country?

Each result is a JSON object packed with geographic, demographic, and economic indicators including gdp , gdp_per_capita , population , pop_density , capital , currency , life_expectancy_male , unemployment , co2_emissions , and internet_users , among many others. For a country's flag image use the Country Flag API , and for deeper population or GDP figures see the Population API and GDP API .

How do I look up a specific country with the /v1/country endpoint?

Pass the name parameter, which accepts a plain English name, a 2-letter ISO-3166 alpha-2 code, or a 3-letter ISO-3166 alpha-3 code (for example name=United States or name=US ). For city-level lookups instead, check out the City API .

Can I filter or search for countries by their statistics?

Yes, the /v1/country endpoint supports filter parameters such as currency , min_population , max_population , min_gdp , max_gdp , min_unemployment , and min_fertility , and you can cap the number of matches with the limit parameter (between 1 and 30 , default 5 ). See our APIs for related data sources you can combine with these results.

What is the /v1/allcountries endpoint and how does it differ from /v1/country?

The premium-only /v1/allcountries endpoint returns a JSON array of every 2-letter country code for the countries, territories, and regions we cover, whereas /v1/country returns full statistics objects for countries matching your parameters. Upgrade details are on our pricing page .

Country API

The Country API provides key geographic, demographic, and economic statistics about every country in the world.

Available endpoints:

/v1/country - Get country data from given parameters
/v1/allcountries - Get a list of all countries

Every country result includes flag image URLs (flag_url and flag_square_url). For flags of territories and regions (e.g. England, the EU), check out the Country Flag API.

Online

(4.8)

From 8,067 users

400+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average	P50	P75	P90	P95
359ms	386ms	422ms	678ms	1264ms

Didn't find what you were looking for? Suggest an improvement

2 endpoints

https://api.api-ninjas.com/v1/country

Get country data from given parameters. Returns a list of country statistics that satisfy the parameters.

Parameters

name optional
Plain English name, 2-letter ISO-3166 alpha-2, or 3-letter ISO-3166 alpha-3 code of country.
currency optional
3-letter currency code of country (e.g. USD).
min_gdp optional
Minimum gross domestic product (GDP) of country, in US Dollars.
max_gdp optional
Maximum gross domestic product (GDP) of country, in US Dollars.
min_population optional
Minimum population of country (in thousands).
max_population optional
Maximum population of country (in thousands).
min_area optional
Minimum surface area of country in km².
max_area optional
Maximum surface area of country in km².
min_unemployment optional
Minimum unemployment rate in %.
max_unemployment optional
Maximum unemployment rate in %.
min_gdp_growth optional
Minimum GDP growth rate in %.
max_gdp_growth optional
Maximum GDP growth rate in %.
min_infant_mortality optional
Minimum infant mortality rate per 1,000 live births.
max_infant_mortality optional
Maximum infant mortality rate per 1,000 live births.
min_fertility optional
Minimum fertility rate (average number of children per woman).
max_fertility optional
Maximum fertility rate (average number of children per woman).
min_urban_pop_rate optional
Minimum urban population rate in %.
max_urban_pop_rate optional
Maximum urban population rate in %.
limit optional
How many results to return. Must be between 1 and 30. Default is 5.

Headers

X-Api-Key required
API Key associated with your account.

Response

The /v1/country endpoint returns a JSON array of objects, each with the following fields, or an error if the request is unsuccessful.

name
Country name
iso2
2-letter ISO-3166 alpha-2 country code
gdp
Gross domestic product (GDP) in millions of US Dollars
gdp_growth
GDP growth rate in %
gdp_per_capita
GDP per capita in US Dollars
population
Total population (in thousands)
pop_growth
Population growth rate in %
pop_density
Population density per km²
currency
Currency object with code (3-letter currency code) and name
capital
Capital city
region
Geographic region
surface_area
Surface area in km²
unemployment
Unemployment rate in %
employment_agriculture
Employment in agriculture sector in %
employment_industry
Employment in industry sector in %
employment_services
Employment in services sector in %
life_expectancy_male
Life expectancy for males in years
life_expectancy_female
Life expectancy for females in years
infant_mortality
Infant mortality rate per 1000 live births
fertility
Fertility rate (average number of children per woman)
sex_ratio
Sex ratio (males per 100 females)
urban_population
Urban population as % of total population
urban_population_growth
Urban population growth rate in %
primary_school_enrollment_male
Primary school enrollment rate for males in %
primary_school_enrollment_female
Primary school enrollment rate for females in %
secondary_school_enrollment_male
Secondary school enrollment rate for males in %
secondary_school_enrollment_female
Secondary school enrollment rate for females in %
post_secondary_enrollment_male
Post-secondary school enrollment rate for males in %
post_secondary_enrollment_female
Post-secondary school enrollment rate for females in %
imports
Imports in millions of US Dollars
exports
Exports in millions of US Dollars
co2_emissions
CO2 emissions in millions of metric tons
forested_area
Forested area as % of total land area
threatened_species
Number of threatened species
homicide_rate
Homicide rate per 100,000 people
tourists
Number of tourists (in thousands)
refugees
Number of refugees (in thousands)
internet_users
Internet users as % of total population
telephone_country_codes
Array of telephone country codes
flag_url
URL to the country's flag image (4:3 rectangle, SVG)
flag_square_url
URL to the country's flag image (1:1 square, SVG)

Live Demo

Live demo · no API key required

Query parameters

name

currency

min_population

max_population

min_gdp

Get a free API key to get started — no credit card required.

Headers

X-Api-KeyLog in or sign up to get your API key

GET

https://api.api-ninjas.com/v1/country?name=United%20States

Sample response

[

{

"gdp": 20580223,

"sex_ratio": 97.9,

"surface_area": 9833517,

"life_expectancy_male": 76.3,

"unemployment": 3.9,

"imports": 2567490,

"homicide_rate": 5,

"currency": {

"code": "USD",

"name": "Us Dollar"

"iso2": "US",

"gdp_growth": 2.9,

"employment_services": 79,

"urban_population_growth": 0.9,

"secondary_school_enrollment_female": 98.7,

"employment_agriculture": 1.3,

"capital": "Washington, D.C.",

"co2_emissions": 4761.3,

"forested_area": 33.9,

"tourists": 79746,

"exports": 1644280,

"life_expectancy_female": 81.3,

"post_secondary_enrollment_female": 102,

"post_secondary_enrollment_male": 75,

"primary_school_enrollment_female": 101.4,

"infant_mortality": 5.8,

"secondary_school_enrollment_male": 99.2,

"threatened_species": 1655,

"population": 331003,

"urban_population": 82.5,

"employment_industry": 19.7,

"name": "United States",

"pop_growth": 0.6,

"region": "Northern America",

"pop_density": 36.2,

"internet_users": 87.3,

"gdp_per_capita": 62917.9,

"fertility": 1.8,

"refugees": 1043.2,

"primary_school_enrollment_male": 102.2,

"telephone_country_codes": [

"1"

"flag_url": "https://media.api-ninjas.com/flags/4x3/8L07WqeX/us.svg",

"flag_square_url": "https://media.api-ninjas.com/flags/1x1/KoHP0ZTO/us.svg"

}

]

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/country?name=United%20States" \
  -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.