An overview of the WOPR API for developers

WorldPop Research Group
University of Southampton

28 August 2020

Introduction

The WOPR REST API provides a way for web servers and other computers to communicate with the WorldPop Open Population Repository to submit requests for data and to retrieve results. This can be used to:

  1. Automate the process of downloading the latest WorldPop population data sets and documentation,
  2. Submit spatial queries (points or polygons) to the WorldPop server to retrieve population estimates within user-defined geographic areas,
  3. Get estimates of population sizes for specific demographic groups (i.e. age and sex), and
  4. Get probabilistic estimates of uncertainty for all population estimates.

This document provides instructions how to utilize each of the following API endpoints:

Data Catalogue
https://wopr.worldpop.org/api/v1.0/data

Spatial Queries
https://api.worldpop.org/v1/wopr/pointtotal
https://api.worldpop.org/v1/wopr/pointagesex
https://api.worldpop.org/v1/wopr/polytotal
https://api.worldpop.org/v1/wopr/polyagesex

Retrieve Results
https://api.worldpop.org/v1/tasks


Data Download

API Endpoint:
https://wopr.worldpop.org/api/v1.0/data


This API endpoint will return the WOPR data catalogue in JSON format. The JSON is organized with the following hierarchical levels:

country A three letter code to identify the country that the dataset represents. WOPR uses ISO country codes to abbreviate country names. For example 'NGA' regers to Nigeria.

category The category describes the types of data available for a given country. For example, 'Population' refers to population estimates.

version The version of a data release for a given country and data type. For example, 'v1.2'.

file_type The file_type describes the category of individual files. For example, 'gridded' refers to gridded population estimates, and 'sql' refers to the SQL database used on the WOPR backend to support the spatial queries described below.


Each file has the following attributes:

title is a short descriptive name of the data set.

desc is a longer description of the data set.

citation is the recommended citation.

doi is the official published DOI (digital object identifier) that can be used for citations. The DOI refers to a stable and permanent version of the file that is stored at ftp://ftp.worldpop.org/repo/wopr. These files may differ slightly from the files stored at https://wopr.worldpop.org if minor changes were made since the time of the DOI publication.

file is the file name.

file_size is the size of the file on the hard disk (MB).

url is the URL for downloading the file.

date is the date the file was released.

hash is the MD5 hash that can be used to compare files to ensure their contents are identical.

git is the URL for the GitHub repository containing code that is relevant to the data set (e.g. the code used to create the data).



Spatial Queries

Spatial queries can be submitted to WOPR as points or polygon locations in a GeoJSON format using several different WOPR API endpoints that will be described below. Spatial requests are supported for any data releases in the category 'Population' that contain an SQL database file_type='sql' (see Data Download above).

Before describing the API endpoints, a note about the format of the results. WOPR will return population estimates for the queried location and demographic group as a JSON that contains a vector of numbers representing the population estimate for a given location: 122,88,108,119,98,92,98,101,121,103,127,122,103,118,.... A histogram of these numbers will graphically illustrate the population estimate and its uncertainty as a probability distribution:

The most likely population estimate is the mean of this distribution (e.g. 100 people, in this case).

summary(x)
##    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
##   60.00   93.00  100.00   99.97  107.00  142.00

The 95% confidence intervals for the population estimate can be calculated as the 0.025 and 0.975 quantiles:

quantile(x, probs=c(0.025, 0.975))
##  2.5% 97.5% 
##    81   120




Point-based total population

API Endpoint:
https://api.worldpop.org/v1/wopr/pointtotal


This endpoint accepts coordinates for a point location and returns the total population. Requests to this API endpoint require the following arguments:

iso3 The ISO country codes of the country to query (e.g. NGA).

ver The version of the population estimates to query (e.g. 1.2).

lat The latitude of the location to query using the WGS84 coordinate system (e.g. 11.53579).

lon The longitude of the location to query using the WGS84 coordinate system (e.g. 4.850808).


An example of an API request:
https://api.worldpop.org/v1/wopr/pointtotal?iso3=NGA&ver=1.2&lat=11.53579&lon=4.850808


This request returns a task identification number 2a6a2883-3fd7-5fbf-832c-86e5f35e7c5e that can be used to query the result:
https://api.worldpop.org/v1/tasks/2a6a2883-3fd7-5fbf-832c-86e5f35e7c5e


Results for any task id from WOPR can be retrieved in this way, regardless of the endpoint used to submit the request.



Point-based population for specific age-sex group

API Endpoint:
https://api.worldpop.org/v1/wopr/pointagesex


This endpoint accepts coordinates for a point location and returns the population size for a specified age-sex group. Requests to this API endpoint require the following arguments:

iso3 The ISO country codes of the country to query (e.g. NGA).

ver The version of the population estimates to query (e.g. 1.2).

lat The latitude of the location to query using the WGS84 coordinate system (e.g. 11.53579).

lon The longitude of the location to query using the WGS84 coordinate system (e.g. 4.850808).

agesex The age-sex groups for which a population estimate is required. This argument accepts a comma-separated vector of age-sex group identifiers. f0 represents females less than one year old; f1 represents females from age one to four; f5 represents females from five to nine; f10 represents females from 10 to 14; and so on. m0 represents males less than one, etc. The full list of acceptable values: m0, m1, m5, m10, m15, m20, m25, m30, m35, m40, m45, m50, m55, m60, m65, m70, m75, m80, f0, f1, f5, f10, f15, f20, f25, f30, f35, f40, f45, f50, f55, f60, f65, f70, f75, f80.


An example of an API request:
https://api.worldpop.org/v1/wopr/pointagesex?iso3=NGA&ver=1.2&lat=11.53579&lon=4.850808&agesex=m0,m1,f0,f1


This request will return the population of children under five at the specified point location. The task id was 38f18d6e-d7d8-5886-828a-45c29da7f766. This can be used to retrieve the result:
https://api.worldpop.org/v1/tasks/38f18d6e-d7d8-5886-828a-45c29da7f766



Polygon-based total population

API Endpoint:
https://api.worldpop.org/v1/wopr/polytotal


This endpoint accepts a GeoJSON representing a polygon location and returns the total population. Requests to this API endpoint require the following arguments:

iso3 The ISO country codes of the country to query (e.g. NGA).

ver The version of the population estimates to query (e.g. 1.2).

geojson A GeoJSON representing the polygon location to query (see example below).

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              3.2080078125,
              7.0027636819827475
            ],
            [
              3.7902832031250004,
              7.0027636819827475
            ],
            [
              3.7902832031250004,
              7.612997502224103
            ],
            [
              3.2080078125,
              7.612997502224103
            ],
            [
              3.2080078125,
              7.0027636819827475
            ]
          ]
        ]
      }
    }
  ]
}

An example of an API request:
https://api.worldpop.org/v1/wopr/polytotal?iso3=NGA&ver=1.2&geojson={"type":"FeatureCollection","features":[{"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[3.2080078125,7.0027636819827475],[3.7902832031250004,7.0027636819827475],[3.7902832031250004,7.612997502224103],[3.2080078125,7.612997502224103],[3.2080078125,7.0027636819827475]]]}}]}


This request returns a task identification number 06b50b9f-d94d-50b9-916a-1d34b767d00a that can be used to query the result:
https://api.worldpop.org/v1/tasks/06b50b9f-d94d-50b9-916a-1d34b767d00a



Polygon-based population for specific age-sex group

API Endpoint:
https://api.worldpop.org/v1/wopr/polyagesex


This endpoint accepts a GeoJSON representing a polygon location and returns the population size within a specified age-sex group. Requests to this API endpoint require the following arguments:

iso3 The ISO country codes of the country to query (e.g. NGA).

ver The version of the population estimates to query (e.g. 1.2).

geojson A GeoJSON representing the polygon location to query (see example above).

agesex The age-sex groups for which a population estimate is required. This argument accepts a comma-separated vector of age-sex group identifiers. The full list of acceptable values: m0, m1, m5, m10, m15, m20, m25, m30, m35, m40, m45, m50, m55, m60, m65, m70, m75, m80, f0, f1, f5, f10, f15, f20, f25, f30, f35, f40, f45, f50, f55, f60, f65, f70, f75, f80.


An example of an API request:
https://api.worldpop.org/v1/wopr/polyagesex?iso3=NGA&ver=1.2&agesex=m0,m1,f0,f1&geojson={"type":"FeatureCollection","features":[{"type":"Feature","properties":{},"geometry":{"type":"Polygon","coordinates":[[[3.2080078125,7.0027636819827475],[3.7902832031250004,7.0027636819827475],[3.7902832031250004,7.612997502224103],[3.2080078125,7.612997502224103],[3.2080078125,7.0027636819827475]]]}}]}

This request returns a task identification number b6418707-d795-56ef-9d06-c469e3697782 that can be used to query the result:
https://api.worldpop.org/v1/tasks/b6418707-d795-56ef-9d06-c469e3697782


Contributing

The WorldPop Open Population Repository (WOPR) was developed by the WorldPop Research Group within the Department of Geography and Environmental Science at the University of Southampton. Funding was provided by the Bill and Melinda Gates Foundation and the United Kingdom Department for International Development (OPP1182408). Professor Andy Tatem provides oversight of the WorldPop Research Group. The wopr R package was developed by Doug Leasure. Maksym Bondarenko and Niko Ves developed the API backend server. Edith Darin added multi-lingual functionality to the Shiny app and the French translation. Natalia Tejedor Garavito proofread the Spanish translation. Gianluca Boo created the WOPR logo. Population data have been contributed to WOPR by many different researchers within the WorldPop Research Group.

Suggested Citation

Leasure DR, Bondarenko M, Darin E, Tatem AJ. 2021. wopr: An R package to query the WorldPop Open Population Repository, version 1.0.0. WorldPop, University of Southampton. doi: 10.5258/SOTON/WP00716. https://github.com/wpgp/wopr

License

GNU General Public License v3.0 (GNU GPLv3)