Advanced Data API Queries

The root URL for the API is https://api.worldpop.org/v1/services. Accessing the root URL (for example through a browser window) returns a JSON list of currently available services and datasets

{
    "services": [
        "stats",
        "sample"
    ],
    "datasets": {
        "wpgppop": "Global per country 2000-2020 datasets represent the outputs from a project focused on construction of consistent 100m resolution population count datasets for all countries of the World for each year 2000-2020.",
        "wpgpas": "Age and sex structures, Global per country 2000-2020"
    }
}

The API currently contains two services which run on the servers: “stats” and “sample”. “stats” is the primary service to return population totals. There are currently two datasets available in the API containing the total population from the WorldPop Global Project (“wpgppop”) and the total population in age and sex categories (“wpgpas”).

Constructing queries

The primary operation when using the API is to construct URLs containing required and optional parameters and passing values to those parameters. Each URL must specify a service and a dataset.
In addition:

Required parameters:

year – year of the dataset. For WorldPop Global Project this is 2000-2020
geojson – a GeoJSON format for geographic data structures (https://geojson.org/)

Optional parameters:

key – API key provided to users who wish to execute larger queries and other special functionality
runasync – Boolean option to execute queries asynchronously, default is True

Within the URL, parameters are separated by the “&” (ampersand) and values are passed within braces (“{ }”). For example, to get a total population or age and sex population totals in a specified area, the following query should be used:

api.worldpop.org/v1/services/stats?dataset={dataset_name}&year={year}&geojson={geojson}&key={your_key}

Where {dataset_name} is “wpgppop” or “wpgpas” , {year} is a year of dataset (2000-2020) and {geojson} is a geojson. “key” parameters is an {your_key} to have more options REST API functionality

Example (copy and paste into a browser to test):

https://api.worldpop.org/v1/services/stats?dataset=wpgppop&year=2010&geojson={“type”:”FeatureCollection”,”features”:[{“type”:”Feature”,”properties”:{},”geometry”:{“type”:”Polygon”,”coordinates”:[[[10.546875,47.62097541515849],[9.95361328125,46.437856895024204],[11.315917968749998,45.98169518512228],[12.63427734375,46.66451741754235],[12.65625,47.85740289465826],[10.546875,47.62097541515849]]]}}]}

{
    "status": "created",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "taskid": "ed53cf88-a6c4-5ad2-968c-93775c480661"
}

This task was successfully created. Because this is an asynchronous task, it was successfully added to the task queue and a “taskid” is returned.

To monitor the task or to retrieve the results, a separate API query is constructed:

https://api.worldpop.org/v1/tasks/{taskid}

Example Response
https://api.worldpop.org/v1/tasks/ee2e98e9-b9ea-5eb6-9c26-ecb8cb3469a3

{
    "status": "finished",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "data": {
        "total_population": 1705754.5
    },
    "taskid": "ee2e98e9-b9ea-5eb6-9c26-ecb8cb3469a3",
    "startTime": "2019-10-16 10:26:03.396803",
    "endTime": "2019-10-16 10:26:04.447173",
    "executionTime": 1
}

If the task is completed successfully than the status will be “finished” with a “status_code” equal to 200. If an error occurred, the “error” flag will return True and any error message from the server will passed.

The “data” item in the response from the “stats” service will contain a calculated total_population or age and sex population pyramid for the spatial area defined by the GeoJSON feature.

Example to return the Age&Sex population in “wpgpas”:
https://api.worldpop.org/v1/services/stats?dataset= wpgpas&year=2010&geojson={“type”:”FeatureCollection”,”features”:[{“type”:”Feature”,”properties”:{},”geometry”:{“type”:”Polygon”,”coordinates”:[[[10.546875,47.62097541515849],[9.95361328125,46.437856895024204],[11.315917968749998,45.98169518512228],[12.63427734375,46.66451741754235],[12.65625,47.85740289465826],[10.546875,47.62097541515849]]]}}]}

{
    "status": "created",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "taskid": "308d3762-21ca-5280-8a08-d1bbc67aa27d"
}

To monitor the task by the taskid:
https://www.api.worldpop.org/v1/tasks/308d3762-21ca-5280-8a08-d1bbc67aa27d

{
    "status": "finished",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "data": {
        "agesexpyramid": [
            {
                "class": "0",
                "age": "0 to 1",
                "male": 9344.5,
                "female": 8928.76
            },
            {
                "class": "1",
                "age": "1 to 5",
                "male": 34786.76,
                "female": 33531.97
            },


.....
.....
.....

            {
                "class": "75",
                "age": "75 to 80",
                "male": 34286.57,
                "female": 42805.62
            },
            {
                "class": "80",
                "age": "80 and over",
                "male": 29320.66,
                "female": 44696.16
            }
        ]
    },
    "taskid": "308d3762-21ca-5280-8a08-d1bbc67aa27d",
    "startTime": "2019-10-16 12:05:34.375312",
    "endTime": "2019-10-16 12:05:37.194524",
    "executionTime": 3
}

Asynchronous Execution

Some larger tasks and operations are very involved and take longer to complete. To prevent the client from blocking while the operation completes and to provide a progress report, these operations are executed in an asynchronous manner by putting the request in a job queue and assigning a task ID (as shown above). However, this process can be controlled by passing in the “runasync” parameter in addition to the operational parameters.

“runasync” A boolean to indicate if the operation needs to be run asynchronously. Values: true | false. Default is true.

If “runasync” parameter is false then the results will be executed while the user waits (for up to 30 seconds) and return immediately when it is ready. An example query using the runasync parameter is shown below.

https://api.worldpop.org/v1/services/stats?dataset=wpgppop&year=2010&geojson={“type”:”FeatureCollection”,”features”:[{“type”:”Feature”,”properties”:{},”geometry”:{“type”:”Polygon”,”coordinates”:[[[10.546875,47.62097541515849],[9.95361328125,46.437856895024204],[11.315917968749998,45.98169518512228],[12.63427734375,46.66451741754235],[12.65625,47.85740289465826],[10.546875,47.62097541515849]]]}}]}&runasync=false

Example output

{
    "status": "finished",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "data": {
        "total_population": 1806541.78
    },
    "taskid": "fc1517b8-e7bd-5d98-a5a1-a2beb6e6635b",
    "startTime": "2019-11-27 00:16:15.322276",
    "endTime": "2019-11-27 00:16:18.912877",
    "executionTime": 3
}

Note: if a synchronous task takes more than 30 seconds to execute, the server will automatically respond with a task ID and the user should monitor the progress and retrieve the results using the taskid as shown above.

{
    "status": "created",
    "status_code": 200,
    "error": false,
    "error_message": null,
    "taskid": "964217ee-a5b3-503e-926e-c982c1414618"
}