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:

For flag images of countries, check out the Country Flag API instead.

(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

/v1/country GET

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.

  • max_population  optional

    Maximum population of country.

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

  • max_infant_mortality  optional

    Maximum infant mortality rate in %.

  • min_fertility  optional

    Minimum fertility rate in %.

  • max_fertility  optional

    Maximum fertility rate in %.

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

Sample Request Live Demo!

name
currency
min_population
max_population
min_gdp

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

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

Headers

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

Sample Response

JSON
[
    {
      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.0",
      post_secondary_enrollment_male:"75.0",
      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"
      ]
    }
]

Code Examples

1 2 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.

/v1/allcountries GETPremium 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

JSON
[
    "AD",
    "AE",
    "AF",
    "AG",
    "AI",
    "AL",
    "AM",
    "..."
]

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.