PopEx API Access & Usage Guide

Population Explorer’s API allows analysts and decision-makers to pull demographic data directly into their own workflows. Instead of working exclusively inside the web application, you can programmatically query population totals, density, and age–sex breakdowns for any polygon you define. Each paid account comes with an API token and a monthly allowance of calls, making it simple to test small-scale analyses or integrate population data into larger automated pipelines. With straightforward request and response formats, the API is designed to be accessible to both technical teams and business users working with spatial datasets.

Prerequisites

• A paid PopEx account (Pro or Enterprise).

• An API token, visible in:
  - In-app → Person icon (upper left) → Account & Billing
  - Marketing site → My Account → Account Info

• An API tool of your choice (curl, Postman, Python, R, etc.).

• Familiarity with JSON input/output.

Features

• Direct programmatic access to Population Explorer datasets (LandScan 2016–2023, WorldPop 2024+).

• Returns population totals, age/sex breakdowns, and demographic metrics.

• Supports polygon queries — send your own geometries.

• Provides quota management: 100 free calls/month included in all paid accounts (Pro, Enterprise); more available via direct purchase.

Instructions

Step 1: Locate your API token

In-app path: Person icon → Account & Billing
Marketing site path: My Account → Account Info

Step 2: Structure your request

Send an HTTP POST request. Required headers:

Authorization: Token YOUR_API_TOKEN
Content-Type: application/json
Ds-Year: YYYY

Authorization: Token YOUR_API_TOKEN
Content-Type: application/json
Ds-Year: YYYY

Authorization: Token YOUR_API_TOKEN
Content-Type: application/json
Ds-Year: YYYY

Step 3: Provide a polygon

Include a type: Polygon payload with coordinates. Coordinates must be in GeoJSON format (longitude, latitude).

Example Request

curl -X POST 'https://populationexplorer.com/api/geodata/population/' -H 'Authorization: Token YOUR_API_TOKEN' -H 'Ds-Year: 2021' -H 'Content-Type: application/json' -d '{
  "type": "Polygon",
  "coordinates": [
    [[6.9462,50.9500,0.0],[6.9522,50.9498,0.0],[6.9522,50.9460,0.0],[6.9462,50.9462,0.0],[6.9462,50.9500,0.0]]
  ]
}'

curl -X POST 'https://populationexplorer.com/api/geodata/population/' -H 'Authorization: Token YOUR_API_TOKEN' -H 'Ds-Year: 2021' -H 'Content-Type: application/json' -d '{
  "type": "Polygon",
  "coordinates": [
    [[6.9462,50.9500,0.0],[6.9522,50.9498,0.0],[6.9522,50.9460,0.0],[6.9462,50.9462,0.0],[6.9462,50.9500,0.0]]
  ]
}'

curl -X POST 'https://populationexplorer.com/api/geodata/population/' -H 'Authorization: Token YOUR_API_TOKEN' -H 'Ds-Year: 2021' -H 'Content-Type: application/json' -d '{
  "type": "Polygon",
  "coordinates": [
    [[6.9462,50.9500,0.0],[6.9522,50.9498,0.0],[6.9522,50.9460,0.0],[6.9462,50.9462,0.0],[6.9462,50.9500,0.0]]
  ]
}'

Example Response

{
  "results": [
    {
      "population_data": {
        "female": 3079.6,
        "male": 2985.8,
        "sum": 6065.3,
        "Pyramids": [
          {"AgeGroup":"0_4","MalePop":84.3,"FemalePop":80.0,"TotalPop":164.3},
          {"AgeGroup":"5_9","MalePop":127.2,"FemalePop":120.6,"TotalPop":247.7}
        ]
      },
      "quota": 71993
    }
  ]
}

{
  "results": [
    {
      "population_data": {
        "female": 3079.6,
        "male": 2985.8,
        "sum": 6065.3,
        "Pyramids": [
          {"AgeGroup":"0_4","MalePop":84.3,"FemalePop":80.0,"TotalPop":164.3},
          {"AgeGroup":"5_9","MalePop":127.2,"FemalePop":120.6,"TotalPop":247.7}
        ]
      },
      "quota": 71993
    }
  ]
}

{
  "results": [
    {
      "population_data": {
        "female": 3079.6,
        "male": 2985.8,
        "sum": 6065.3,
        "Pyramids": [
          {"AgeGroup":"0_4","MalePop":84.3,"FemalePop":80.0,"TotalPop":164.3},
          {"AgeGroup":"5_9","MalePop":127.2,"FemalePop":120.6,"TotalPop":247.7}
        ]
      },
      "quota": 71993
    }
  ]
}

Verification

• Ensure your token is accepted (401 Unauthorized = invalid token).

• Check that the quota field in the response matches your remaining calls.

• Validate that population_data.sum equals the total population for your polygon.

Common Errors

• 401 Unauthorized: Invalid or missing API token.

• 403 Forbidden: Token belongs to an unpaid account.

• 403 Starter Plan: Starter accounts cannot use the API (upgrade to Pro or Enterprise).

• 429 Too Many Requests: Monthly quota exceeded (100 free calls); contact PopEx to purchase more.

• 400 Bad Request: Malformed polygon JSON.

Best Practices

• Keep polygons as simple as possible to avoid timeouts.

• Cache results if running repeated queries on the same area.

• Monitor quota usage via the quota field in responses.

• Upgrade or purchase additional calls if you expect heavy API usage.

Need More Help?

If you run into issues, please contact us.