API Documentation

The JMP WASH data API gives free, programmatic access to the WHO/UNICEF Joint Monitoring Programme (JMP) estimates for drinking water, sanitation and hygiene (WASH). It covers three settings: households, schools and health care facilities. You can use it to pull estimates directly into Excel, R, Python or your own applications, without downloading and combining files by hand.

The API works like a REST API. You make an HTTP GET request to a URL, and the filters you want go in the URL's query string. No registration or API key is required. The API returns data as JSON or as CSV.

Base URL: https://api.washdata.org/v1

Interactive reference: https://api.washdata.org/v1/doc. It lists every parameter and response field for every dataset, and you can try requests in your browser.

Overview: a simple example

The easiest way to see how the API works is to paste a URL into your browser. This request returns household estimates for Kenya:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&year[]=2022

You'll see a JSON response. It has a query section that repeats the filters you used, some counts, and a results list with one entry per estimate:

{
  "query": { "country": ["KEN"] },
  "result_count": 2,
  "total_count": 2,
  "limit": 10000,
  "offset": 0,
  "results": [
    {
      "country": "KEN",
      "year": 2022,
      "residence_type": "total",
      "service_type": "Drinking water",
      "service_level": "Basic service",
      "value": 62.4,
      "population": 54027487
    },
    { "...": "..." }
  ]
}

Values shown are for illustration only.

To download the same data as a spreadsheet, add format=csv to the end of the URL:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv

Each estimate's value is the percentage of the population (or of schools or health care facilities) that uses that service level. population is the population the estimate applies to.

How to query

Every request URL has the same three parts:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&year[]=2022
                            └── 1 ──┘ └────── 2 ──────┘ └────────── 3 ──────────┘

1. Data source: which setting the data covers. Use household, school or healthcare.
2. Dataset: what kind of data you want, such as country estimates, regional estimates or population. See Available datasets.
3. Filters: optional parameters that narrow the results. They come after a ? and are separated by &.

If you leave out the filters, you get everything in the dataset. This request returns every country estimate for schools:

https://api.washdata.org/v1/school/estimates/country?format=csv

Available datasets

In the paths below, replace {source} with household, school or healthcare.

The last three are reference datasets. They're mainly useful for looking up the exact names and codes to use in your filters. See How to find valid filter values.

How to filter by service type and service level

JMP estimates are organised by service type and service level.

The service types are Drinking water, Sanitation and Hygiene. Each type has a service ladder, a set of levels from worst to best. For example, the sanitation ladder runs from Open defecation through Unimproved and Limited service to Basic service and Safely managed service.

Use service_type[] to choose a service type:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&service_type[]=Sanitation

Use service_level[] to choose one or more levels:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&service_type[]=Sanitation&service_level[]=Basic%20service

Values must match the names used in the data exactly, including capital letters. Values containing spaces must be URL-encoded, so Basic service becomes Basic%20service. Most browsers, spreadsheet tools and programming libraries encode values for you.

To see every service level and its definition, use the service-levels dataset. See How to find valid filter values.

How to filter by place

Countries

Countries are identified by their three-letter ISO3 code, such as KEN for Kenya or IND for India. Use country[]:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN

Parameters that end in [] can be repeated to request several values at once. This request returns estimates for Kenya, Uganda and Tanzania:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&country[]=UGA&country[]=TZA

Regions

You can request every country in a region by combining region_type and region. region_type is the regional grouping and region is the name of a region within it. This request returns country estimates for every country in the SDG region Sub-Saharan Africa:

https://api.washdata.org/v1/household/estimates/country?region_type=sdg&region=Sub-Saharan%20Africa

To get estimates for the region as a whole, rather than for each country in it, use the regional estimates dataset. Here you can repeat both parameters:

https://api.washdata.org/v1/household/estimates/region?region_type[]=sdg&region[]=Sub-Saharan%20Africa

The global total is available with region_type[]=world&region[]=World.

The main regional groupings are:

Not every grouping is available for every data source.

Urban and rural areas

Most estimates are given for the whole population and separately for urban and rural areas. Use residence[] with total, urban or rural:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&residence[]=urban&residence[]=rural

Subnational areas

The subnational dataset gives estimates for areas within a country. Use region_name[] to choose specific areas:

https://api.washdata.org/v1/household/estimates/subnational?country[]=IND&region_name[]=Maharashtra

Use the country-subregions dataset to find the area names available for a country.

How to filter by year

Use year[] to request one or more specific years:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&year[]=2015&year[]=2022

Use year_from and year_to to request a range of years. Both ends of the range are included, and you can use either one on its own:

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&year_from=2015&year_to=2022

You can't use year[] and year_from/year_to in the same request. If you do, the API returns an error.

The subnational and wealth quintile datasets come from individual surveys. For these, you can add latest=1 to return only results from each country's most recent survey. When you use latest, any year filters are ignored:

https://api.washdata.org/v1/household/estimates/quintile?country[]=NGA&latest=1

How to choose the response format

The API returns JSON by default. JSON is best if you're building an application or website.

Add format=csv to get a CSV file instead. CSV is best for Excel, R, Python and most analysis tools. When you open a CSV URL in a browser, the file downloads with a name based on your query.

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv

If you're making requests from code, you can also request CSV by sending the HTTP header Accept: text/csv.

How to page through results

Large JSON responses are split into pages. By default, each page contains up to 10,000 results. The response tells you where you are:

• result_count is the number of results on this page.
• total_count is the total number of results that match your filters.
• limit is the maximum number of results per page.
• offset is the number of results skipped before this page.

Use limit to change the page size, up to a maximum of 50,000, and offset to move through the pages. This request returns the second page of 5,000 results:

https://api.washdata.org/v1/household/estimates/country?limit=5000&offset=5000

If total_count is greater than offset plus result_count, there are more pages to fetch.

CSV downloads aren't paged. A CSV request returns every matching result in one file, unless you set limit yourself.

How to find valid filter values

Filter values must match the names and codes used in the data exactly. If a request returns no results, the most likely cause is a misspelt name or an unknown code.

Three reference datasets list the valid values. Each one can be downloaded as CSV.

Countries and the regions they belong to:

https://api.washdata.org/v1/household/country-regions?format=csv

This returns each country's ISO3 code and name, and the region it belongs to in each regional grouping (sdg, who, income and so on). Use it to look up codes for country[] and names for region.

Service types, ladders and levels:

https://api.washdata.org/v1/household/service-levels?format=csv

This returns each service level, the service type and ladder it belongs to, and its definition. Use it to look up names for service_type[] and service_level[].

Subnational areas:

https://api.washdata.org/v1/household/country-subregions?country[]=IND&format=csv

This returns the subnational areas available for each country. Use it to look up names for region_name[].

The values differ between data sources, so request the reference data for the data source you're using (household, school or healthcare).

Understanding the results

Each dataset returns slightly different fields. The most common are:

The interactive reference lists every field for every dataset.

Errors

If the API can't answer a request, it returns an HTTP error status with a message explaining the problem. The most common is 400 Bad Request, for example when year[] and year_from are used together, or when year_from is later than year_to.

A request that runs successfully but matches no data returns an empty results list (or a CSV file with only a header row). This is not an error.

Examples

Basic drinking water services in Kenya, urban and rural, 2015 to 2022

https://api.washdata.org/v1/household/estimates/country?country[]=KEN&service_type[]=Drinking%20water&service_level[]=Basic%20service&residence[]=urban&residence[]=rural&year_from=2015&year_to=2022&format=csv

Sanitation estimates for every country in 2022

https://api.washdata.org/v1/household/estimates/country?service_type[]=Sanitation&year[]=2022&format=csv

Global and SDG regional estimates for hygiene

https://api.washdata.org/v1/household/estimates/region?region_type[]=world&region_type[]=sdg&service_type[]=Hygiene&format=csv

Drinking water services in schools in Sub-Saharan Africa

https://api.washdata.org/v1/school/estimates/country?region_type=sdg&region=Sub-Saharan%20Africa&service_type[]=Drinking%20water&format=csv

Basic sanitation by wealth quintile in Nigeria, latest survey

https://api.washdata.org/v1/household/estimates/quintile?country[]=NGA&service_type[]=Sanitation&service_level[]=Basic%20service&latest=1&format=csv

Urban and rural population of Kenya since 2000

https://api.washdata.org/v1/household/population?country=KEN&year_from=2000&format=csv

Using the API in other tools

Any tool that can read a CSV file from a web address can use the API. Each example below loads Kenya's household estimates.

Excel

1. Go to Data → Get Data → From Other Sources → From Web.
2. Paste the URL: https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv
3. Select OK, then Load.

The data loads into a new sheet. To fetch the latest data later, use Data → Refresh All.

R

library(readr)

url <- "https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv"
data <- read_csv(url)

Python

import pandas as pd

url = "https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv"
data = pd.read_csv(url)

To work with JSON instead, use the requests library:

import requests

response = requests.get(
    "https://api.washdata.org/v1/household/estimates/country",
    params={"country[]": ["KEN", "UGA"], "service_type[]": "Sanitation"},
)
results = response.json()["results"]

requests encodes the parameter values for you, so you can write Drinking water with a space.

Command line

curl -o kenya.csv "https://api.washdata.org/v1/household/estimates/country?country[]=KEN&format=csv"

Query parameters

This table lists the main query parameters and the datasets they apply to. The interactive reference has the complete list for each dataset.