API docs
Base URL is this site. All responses are JSON. Machine-readable spec: /v1/openapi.json.
Auth
Send your key in the x-api-key header, or as Authorization: Bearer <key>. Get a free key on the home page.
Usage is counted per site. Each response carries x-usage-used and x-usage-limit headers. Failed calls are not counted.
Endpoints
GET/v1/risk
All hazards for one place. Pass lat and lon, or address.
curl "/v1/risk?lat=6.5244&lon=3.3792" -H "x-api-key: $CLIMATRIX_KEY"POST/v1/risk/batch
Score many sites in one call. Free plan: 5 per call. Paid plans: 25 per call. Batch returns river flood plus the five historical climate hazards.
curl -X POST "/v1/risk/batch" \
-H "x-api-key: $CLIMATRIX_KEY" -H "content-type: application/json" \
-d '{"sites":[{"id":"lagos-hq","lat":6.5244,"lon":3.3792},{"id":"dubai-dc","lat":25.2048,"lon":55.2708}]}'GET/v1/hazards/{type}
One hazard in depth, with its method and scoring curve. Types: river_flood, heat, drought, heavy_rain, wind, cold, wildfire, air_quality.
GET/v1/hazards
Every hazard, its method, curves and data source. No key needed.
GET/v1/usage
Your plan and usage this month.
POST/v1/keys
Create a free key. Body: {"email": "you@company.com"}. The key is shown once.
GET/v1/plans · /v1/health
Plan limits, and a health check.
Response fields
| Field | Meaning |
|---|---|
overall | Score 0-100, grade A-E, and the top risks. |
hazards.*.score | 0 is lowest risk, 100 is highest. |
hazards.*.grade | A 0-19, B 20-39, C 40-59, D 60-79, E 80-100. |
hazards.*.metrics | The raw numbers behind the score. |
hazards.*.trend | First half of the period vs second half. |
unavailable | Hazards we could not score here, and why. |
sources | Every dataset used, with its licence. |
data_version | Changes when methods or data change. |
Method
Historical hazards use NASA POWER daily data for 2005-2024 at the MERRA-2 grid cell (0.5 x 0.625 degrees, about 50 km). Years with fewer than 330 valid days are skipped. Values outside physical limits are dropped before scoring.
| Hazard | What drives the score |
|---|---|
| River flood | JRC/GloFAS v2.1 water depth at the ~90 m pixel for 1-in-10, 100 and 500-year floods. 10-year band 70-100, 100-year band 40-69, 500-year band 20-39, 100-year flood within ~200 m: 10. Depths over 50 m are dropped as model errors. Points inside a river channel read as deep water. No flash flood, coastal surge or flood defences. |
| Extreme heat | Days a year at or over 35 C, and the hottest day a year. Higher of the two. |
| Drought | 40% low yearly rain, 30% swing between years, 30% longest dry spell. |
| Heavy rain | Wettest day a year, and days over 50 mm. Higher of the two. |
| Strong wind | Peak 10 m wind a year (hourly mean, not gusts). |
| Frost and cold | Nights a year at or below 0 C. |
| Wildfire now | NASA FIRMS VIIRS detections within 25 km, last 7 days. |
| Air quality | Latest PM2.5 from the nearest OpenAQ station within 25 km and 72 hours, as US AQI (EPA 2024 breakpoints, capped at 500). |
| Overall | 70% the worst hazard + 30% the second worst. |
Exact curves: /v1/hazards. Test results against real floods, official flood maps and weather stations: /accuracy.
Limits
Grid-cell data smooths out local extremes, so treat scores as screening, not engineering. Coastal flood and 2050 projections are coming next. Not for life-safety decisions.
Errors
| Status | Code |
|---|---|
| 400 | missing_location, invalid_lat, invalid_lon, too_many_sites |
| 401 | missing_key, invalid_key |
| 404 | address_not_found, unknown_hazard |
| 429 | quota_exceeded, rate_limited |
| 502 / 504 | upstream_error, upstream_timeout. Safe to retry. |