WSF®API Access

A free, public REST API for built-up area, population and hazard-exposure statistics anywhere in the world. Query it straight from the browser, or generate an API key for higher rate limits.

Getting started

All endpoints live under https://worldsettlementfootprint.com/api and return JSON. The data endpoints are open — no key required — so you can start with a single request:

# Anonymous request — browse the available hazard metadata
curl "https://worldsettlementfootprint.com/api/statistics/hazard_metadata?category=flood"

# Same idea, authenticated with an API key (higher limits)
curl "https://worldsettlementfootprint.com/api/statistics/adm0?ids=ITA" \
  -H "X-API-Key: YOUR_API_KEY"

To authenticate, send your key in the X-API-Key request header. Never put your key in front-end code or a public repository.

Get an API key

Keys are free and tied to your email. We use passwordless sign-in — request a magic link, open it, then create and manage your key.

  1. 1. Request a magic link. Enter your email on the sign-in page. We'll send a one-time link (valid 15 minutes).
  2. 2. Open the link. Clicking it verifies your email and signs you in automatically.
  3. 3. Generate your key. On the API key page create a key. It's shown only once — copy and store it somewhere safe. You can revoke or regenerate it there at any time.
Get your API keyManage existing key

Rate limits, and why you want a key

Anonymous requests are throttled per IP address, shared with everyone else behind the same network. A key raises your burst limit tenfold and gives you a private allowance that nobody else can exhaust.

Anonymous (no key)

100 req / min

Per IP address, shared across everyone on that network (offices, VPNs, NAT). Fine for exploring and light use.

With an API key

1,000 req / min

A dedicated limit tied to your key, so other users on your network can't use up your allowance.

When you exceed the limit the API responds with 429 Too Many Requests and a Retry-After header, wait that many seconds before retrying.

Public endpoints

Every endpoint below accepts GET and needs no authentication. Click a Try it link to open the live JSON response in a new tab.

GET/api/statistics/hazard_metadata

Browse the available hazard categories, subcategories, scenarios, return periods and levels. Use it to discover the values you pass to the statistics endpoint.

Query parameters

category
Filter by hazard category (e.g. flood, heat)
subcategory
Filter by subcategory (e.g. pluvial, fluvial)
scenario
Filter by scenario (e.g. ssp585)
return_period
Filter by return period in years (e.g. 100)
Try it:/api/statistics/hazard_metadata?category=flood
GET/api/statistics/{spatial_aggregation}

Built-up area, population and hazard-exposure statistics for a spatial level. Path value is one of healpix | adm1 | adm0.

Query parameters

ids
ISO 3166 codes — alpha-3 for countries (e.g. ITA), subdivision codes for regions (e.g. IT025) — or HEALPix cells as nside:pixelId (e.g. 64:456). Look up country and region codes.
category / subcategory
Hazard category / subcategory filter
scenario
Scenario for future projections (e.g. ssp585)
return_period / level
Return period (years) and hazard level filter
start_date / end_date
Date range filter (YYYY-MM-DD)
aggregation
Aggregate across selected regions: sum | avg | min | max
Try it:/api/statistics/adm0?ids=ITA

Feedback

Spotted something off, or have a request for the API? Let us know. Your input helps us improve the platform.