Population API

Frequently Asked Questions

• Can I use the Population API for commercial purposes?

  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.

• How do I get an API key and start using the Population 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 Population 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.

• How do I query population data for a specific country?

  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.

• What does each population data point in the response include?

  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.

• Can I filter countries by population size instead of querying by name?

  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.

• Why do I only get a few countries back, and how do I page through more?

  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.