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

Population API

The Population API provides historical, current, and projected future population statistics about every country in the world.

(4.5)

From 8,616 users

3,500+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
314ms354ms364ms685ms1254ms

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

/v1/population GET

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

Get population data from given parameters. Returns a list of up to 5 country population statistics that satisfy the parameters. For more results use the offset parameter.

Parameters

At least one of the following parameters must be set: country, min_population, max_population

  • country  optional

    Country name (case-insensitive) or 2-letter ISO-3166 alpha-2 code of the country. E.g. Japan or JP.

  • min_population  optional

    Minimum population of country.

  • max_population  optional

    Maximum population of country.

  • offset  optional

    Offset results for pagination.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON object with the following fields or an error if the request is unsuccessful.

  • country_name

    The name of the country.

  • historical_population

    Array of historical population data objects, each containing the following fields:

    • year

      The year for which the population data is recorded.

    • population

      Total population count for the country in the given year.

    • yearly_change_percentage

      Percentage change in population from the previous year (can be positive or negative).

    • yearly_change

      Absolute change in population from the previous year (can be positive or negative).

    • migrants

      Net number of migrants (immigrants minus emigrants) for the year.

    • median_age

      Median age of the population in years.

    • fertility_rate

      Average number of children born per woman in the population.

    • density

      Population density per square kilometer.

    • urban_population_pct

      Percentage of the total population living in urban areas.

    • urban_population

      Total number of people living in urban areas.

    • percentage_of_world_population

      Percentage of the world's total population represented by this country.

    • rank

      World ranking by population size (1 being the most populous country).

  • population_forecast

    Array of projected future population data objects with the same structure as historical_population.

Sample Request Live Demo!

country
min_population
max_population
offset

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/population?country=Japan

Headers

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

Sample Response

JSON
{
    country_name:"Japan",
    historical_population:[
      {
        year:2024,
        population:123753041,
        yearly_change_percentage:-0.5,
        yearly_change:-617906,
        migrants:153357,
        median_age:49.4,
        fertility_rate:1.22,
        density:339,
        urban_population_pct:92.9,
        urban_population:114979260,
        percentage_of_world_population:1.52,
        rank:12
      },
      {
        year:2023,
        population:124370947,
        yearly_change_percentage:-0.5,
        yearly_change:-626631,
        migrants:175003,
        median_age:49,
        fertility_rate:1.21,
        density:341,
        urban_population_pct:92.7,
        urban_population:115292289,
        percentage_of_world_population:1.54,
        rank:12
      },
      "..."
    ],
    population_forecast:[
      {
        year:2025,
        population:123103479,
        yearly_change_percentage:-0.51,
        yearly_change:-640213,
        migrants:140579,
        median_age:49.8,
        fertility_rate:1.23,
        density:338,
        urban_population_pct:93.1,
        urban_population:114645589,
        percentage_of_world_population:1.5,
        rank:12
      },
      {
        year:2030,
        population:119584121,
        yearly_change_percentage:-0.58,
        yearly_change:-703872,
        migrants:123993,
        median_age:51.5,
        fertility_rate:1.26,
        density:328,
        urban_population_pct:94.3,
        urban_population:112710068,
        percentage_of_world_population:1.4,
        rank:15
      },
      "..."
    ]
}

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/population?country=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.

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Population 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.
  • Set the country parameter to either a country name (case-insensitive) or its 2-letter ISO-3166 alpha-2 code, for example Japan or JP. To enrich those results with broader country-level details, pair it with the Country API.
  • The response returns country_name plus a historical_population array and a population_forecast array, where every entry includes year, population, yearly_change, yearly_change_percentage, migrants, median_age, fertility_rate, density, urban_population, urban_population_pct, percentage_of_world_population, and the country's global rank. Browse related economic datasets in the API catalog.
  • Yes, use the min_population and max_population parameters to return only countries within a population range; at least one of country, min_population, or max_population must be set. For economic indicators across those same countries, try the GDP API or the Unemployment API.
  • The /v1/population endpoint returns up to 5 matching country population records per request, so use the offset parameter to paginate through additional results when filtering by a population range. If you receive an unexpected response, consult the error codes reference.