NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Country API

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

Available endpoints:

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
359ms386ms422ms678ms1264ms

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 km2.

  • max_area  optional

    Maximum surface area of country in km2.

  • 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

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

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.

Premium only

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

Get a list of all 2-letter country codes for countries, territories and regions for which we have statistics.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of strings, or an error if the request is unsuccessful.

Sample Request

https://api.api-ninjas.com/v1/allcountries
Sample response
[
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"..."
]

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/allcountries" \ -H "X-Api-Key: YOUR_API_KEY"

Frequently Asked Questions

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

Explore API integration use cases for recommended APIs and workflow examples.