REST API

Flood Risk API

Programmatically get riverine and coastal flood fields across four return periods, at any site globally.

Depth in metres, cell by cell, across a 6 km grid around the site, from the 1-in-10 to the 1-in-500-year flood.

Request API access

Thanks, you will hear from us shortly.

We will email your API key and the docs.

What the Flood Risk API Returns for Every Site

Riverine and Coastal Flood Depth Grids

Riverine flood depth at 90 m resolution

Each cell holds the flood depth in metres above local ground for the selected return period, across around 4,700 cells near the tropics and more toward the poles. Cells outside the mapped floodplain are null, and whenever the box holds a flooded cell, the response gives the distance from the site to the nearest one.

Coastal flood depth at 1 km resolution

Each cell holds the coastal inundation depth in metres for the selected return period, across about 8 by 8 cells near the tropics and more columns toward the poles. Modelled dry land reads 0.0, and sea and unmodelled cells are null. Every field carries the coastal grid twice, with and without land subsidence. The coastal layer covers the world’s coastlines.

Flood Risk API Endpoints

The flood field endpoints sit under https://api.continuuiti.com/api/v1/flood-field/ and take the same X-API-Key header as every Continuuiti API.

Request and Response Examples

Each site runs asynchronously and typically completes in about a minute. Submit the coordinate, poll the job, read the result, then download the field from bundle_url.

Submit a site

POST /api/v1/flood-field/analyze/
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "lat": 23.69,
  "lon": 58.17,
  "label": "site-01"
}

→ 202 Accepted
{
  "job_id": "ff_5c99a1e6a6c4",
  "status": "PENDING",
  "error": null
}

Retrieve the result (abridged)

GET /api/v1/flood-field/results/ff_5c99a1e6a6c4/
X-API-Key: YOUR_API_KEY

→ 200 OK
{
  "job_id": "ff_5c99a1e6a6c4",
  "status": "COMPLETED",
  "method_version": "flood_field_v1.0",
  "input": {"lat": 23.69, "lon": 58.17, "label": "site-01", "half_km": 3.0},
  "layers": {
    "riverine": {
      "status": "ok",
      "return_periods": [10, 50, 100, 500],
      "depth_semantics": "depth above local ground, metres",
      "width": 71, "height": 65, "native_scale_m": 92.766,
      "site_cell": {"RP10": null, "RP50": null, "RP100": null, "RP500": null},
      "nearest_real_cell_m": 93,
      "band_audit": {
        "RP100_depth": {"real_cells": 1415, "p50": 0.972, "real_max": 4.634}
      }
    },
    "coastal": {
      "status": "ok",
      "return_periods": [10, 50, 100, 500],
      "width": 8, "height": 8, "native_scale_m": 927.662,
      "site_cell": {"RP10": 0.0, "RP50": 0.0, "RP100": 0.0, "RP500": 0.0},
      "site_cell_wtsub": {"RP10": 0.0, "RP50": 0.0, "RP100": 0.0, "RP500": 0.0},
      "subsidence_delta_max_m": {"RP10": 0.0321, "RP50": 0.0321, "RP100": 0.0321, "RP500": 0.0321}
    }
  },
  "generated": "2026-10-21T10:18:25+00:00",
  "bundle_url": "https://<storage>/flood-field-bundles/ff_5c99a1e6a6c4/bundle.json",
  "expires_at": "2027-04-19T10:18:29.236354+00:00"
}

In this example the riverine site cell sits just outside the mapped floodplain at every return period, and the nearest flooded cell is 93 m away. The grid shows the floodplain across the whole box.

Download the full field

GET https://<storage>/flood-field-bundles/ff_5c99a1e6a6c4/bundle.json

→ 200 OK, plain JSON
{
  "summary": { ... },
  "bands": {
    "riverine": {
      "RP10_depth":  [ ...4,615 cells... ],
      "RP50_depth":  [ ... ],
      "RP100_depth": [ ... ],
      "RP500_depth": [ ... ],
      ...
    },
    "coastal": { ...8 grids: four return periods, with and without subsidence... }
  }
}

Grids are flat row-major lists with row 0 at the north edge. The summary’s origin, dx_deg and dy_deg place every cell on a map, and pin.idx marks the site cell.

Batch Processing for Portfolios

Send up to 100 sites in one request as a locations array. Each site runs as its own job and returns its own field. An optional top-level half_km applies to every site. Poll the batch for progress, then page through the per-site results; each result carries its own bundle_url and expiry date.

POST /api/v1/flood-field/batch/analyze/
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "locations": [
    {"lat": 23.69, "lon": 58.17, "label": "site-01"},
    {"lat": 24.34, "lon": 56.71, "label": "site-02"}
  ]
}

→ 202 Accepted
{
  "batch_id": "batch_ff_ab12cd34ef56",
  "status": "PROCESSING",
  "total": 2,
  "skipped": 0
}

Test Your Integration with Dry Run

Add "dry_run": true to any POST. A single-site dry run returns straight away with the summary and a mock field inline under bundle, laid on the real grid geometry, so you can test parsing and mapping before you run real sites. Dry-run responses report the method version flood_field_v1.0_dry_run, which keeps mock results easy to tell apart.

POST /api/v1/flood-field/analyze/
{
  "lat": 23.69,
  "lon": 58.17
}

→ 202 Accepted, job_id
  full field in about a minute

POST /api/v1/flood-field/analyze/
{
  "lat": 23.69,
  "lon": 58.17,
  "dry_run": true
}

→ 200 OK, mock field
  inline under "bundle"

Key Response Fields

Technical Specifications

Flood Risk API Use Cases

Related APIs

Frequently Asked Questions