Querying hazard risk by coordinate with the GEOSLN Hazard API

The Hazard API scores locations against our raster flood hazard layers. This post walks through the single-point endpoint and the bulk endpoint for scoring a whole portfolio at once.

Every result has flood hazard classes for the ten, one-hundred, and five-hundred-year return periods (RP10, RP100, RP500), each from 0 (none) to 5 (very high), read from the European Commission JRC global flood hazard maps, plus a short plain-language AI summary written from those three classes.

The examples use an API key in $GEOSLN_API_TOKEN. Create one on geosln-api.com under Account → API key. It's shown once, so store it somewhere safe (we never email keys). Every call is billed to the credits on that account.

Single coordinate

curl "https://geosln-api.com/gis/risk/?lat=16.470737&lon=-90.534734" \
  -H "Authorization: Token $GEOSLN_API_TOKEN"

The risk levels come back right away. The AI assessment is written by a separate model service, so the response tells you where to pick it up instead of making you wait:

{
  "coordinates": { "lat": 16.470737, "lon": -90.534734 },
  "values": { "RP10": 3, "RP100": 3, "RP500": 4 },
  "assessment": {
    "id": "0b6e…",
    "status": "pending",
    "url": "https://geosln-api.com/gis/risk/assessments/0b6e…/"
  },
  "billing_info": { "credits_used": 0, "credits_remaining": 29, "user_tier": "premium" }
}

Poll assessment.url about once a second until status is ok:

{
  "id": "0b6e…",
  "status": "ok",
  "ai_assessment": "Your property shows MODERATE flood risk under typical conditions, escalating to HIGH risk during severe weather events."
}

A report costs 1 credit, charged when the assessment is ready. If it fails, you aren't charged. A point outside our coverage returns 400 and costs nothing. Risk levels are cached for 24 hours per coordinate, since the underlying rasters only change with a data release.

Bulk scoring

For scoring many locations, such as a portfolio, a list of addresses or a grid, use the bulk endpoint instead of looping over the single-point one. Each record can be a coordinate, a one-line address, or address parts (street, city, state, zip); ref is your own row ID, and properties are passed through to the report:

curl -X POST "https://geosln-api.com/gis/risk/bulk/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token $GEOSLN_API_TOKEN" \
  -d '{
    "records": [
      { "ref": "row-2", "lat": 16.470737, "lon": -90.534734 },
      { "ref": "row-3", "lat": 17.345516, "lon": -88.313333 },
      { "ref": "row-4", "address": "123 Main St, Miami, FL 33101", "properties": { "unit": "A1" } }
    ]
  }'

A bulk request is a job, so it returns 202 Accepted at once, with an estimate of the credits it reserved:

{
  "id": "7f3c…",
  "kind": "risk_bulk",
  "status": "queued",
  "estimate": { "credits_reserved": 3, "valid": 3, "invalid": 0 },
  "status_url": "https://geosln-api.com/gis/jobs/7f3c…/"
}

Poll status_url until the job has succeeded, then download the report as GeoJSON or CSV (?format=csv):

curl -OJ "https://geosln-api.com/gis/jobs/7f3c…/result/?format=geojson" \
  -H "Authorization: Token $GEOSLN_API_TOKEN"

Each record in the report has a status: ok, or a reason it couldn't be scored, such as no_geocode_match or out_of_coverage. Only ok records are charged; the rest of the reservation is released.

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-90.534734, 16.470737] },
  "properties": {
    "ref": "row-2",
    "status": "ok",
    "RP10": 3, "RP100": 3, "RP500": 4,
    "assessment": "Your property shows MODERATE flood risk under typical conditions, escalating to HIGH risk during severe weather events."
  }
}

Full request/response schemas are documented in the interactive Swagger docs.

The same query on the map

The free hazard map runs the single-point query behind the scenes: search a place or click the map, switch the flood return period, and run the report. It's free for 5 reports a day, no account needed: