Hazard API quickstart

1. Get an API key

Create an account, then open Account → API key. The full key is shown once, so store it in your password manager or your app’s environment. We never email keys. Generating a new key stops the old one at once. Send it on every request:

export GEOSLN_API_TOKEN="your-key"
curl -H "Authorization: Token $GEOSLN_API_TOKEN" https://geosln-api.com/...

2. One coordinate

GET /gis/risk/ returns the flood hazard classes for one point straight away. The AI summary is written by a separate service, so the response gives you a URL to poll for it.

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

{
  "coordinates": { "lat": 25.7617, "lon": -80.1918 },
  "values": { "RP10": 2, "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": 41 }
}

Poll assessment.url about once a second until status is ok, then read ai_assessment. A report costs 1 credit, charged when the summary is ready; if it fails you aren’t charged.

3. Bulk jobs

POST /gis/risk/bulk/ takes up to 1,000 records. Each is a coordinate, a one-line address, or address parts (street, city, state, zip). ref is your row ID and properties pass through to the result.

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

It returns 202 Accepted with a job and the credits it reserved. Each record in the result has a status: ok, or why it couldn’t be scored (no_geocode_match, out_of_coverage). Only ok records are charged; the rest of the reservation is released.

4. Convert GIS files

POST /gis/convert-to-geojson/ converts a Shapefile, File Geodatabase (zipped), GeoPackage or KML to GeoJSON as a job, up to 95 MB per upload. 1 credit, charged only on success. Supported formats are listed at GET /gis/available-formats/.

curl -X POST "https://geosln-api.com/gis/convert-to-geojson/" \
  -H "Authorization: Token $GEOSLN_API_TOKEN" \
  -F "format_type=geopackage" \
  -F "[email protected]"

5. Jobs

Bulk scoring and conversion return a job. Poll it, then download the result:

# status and progress
curl -H "Authorization: Token $GEOSLN_API_TOKEN" https://geosln-api.com/gis/jobs/7f3c…/

# result, once status is "succeeded" (bulk: ?format=csv or ?format=geojson)
curl -OJ -H "Authorization: Token $GEOSLN_API_TOKEN" \
  "https://geosln-api.com/gis/jobs/7f3c…/result/?format=csv"

# cancel a running job and release its reserved credits
curl -X DELETE -H "Authorization: Token $GEOSLN_API_TOKEN" https://geosln-api.com/gis/jobs/7f3c…/

Results are kept for 24 hours.

6. Credits and errors

• 1 credit = 1 report, 1 scored bulk record or 1 file conversion. Credits don’t expire.
• Credits are reserved when a job starts and charged only for work that succeeds.
• 400: bad input, including a point outside the data’s coverage (nothing charged). 402: not enough credits. 429: too many requests or jobs at once.
• Your account shows every purchase with its receipt and every credit spent, one line per report or job.

What the data is

The values are flood hazard classes from 0 (none) to 5 (very high) for the 10-, 100- and 500-year return periods, read from the European Commission Joint Research Centre global flood hazard maps (ODbL). They are a screening signal from a global model, not a site survey or a FEMA flood zone. The AI summary is a short plain-language description written from those three classes only.