Black Friday! 50% OFF · Ends Dec 4Black Friday! 50% OFF · Full reports from $3.50 · Ends Dec 4See pricing →

Developers

FloodMaps Developer API

Property-level flood risk for applications and AI assistants.

API version 1.0.0

Overview

The FloodMaps Partner API answers flood-risk questions about a specific property. It is designed for applications and AI assistants that need a trustworthy answer about a single address, not bulk data extraction.

A free tier answers whether a property has flood exposure. A paid tier explains it, and links to the full interactive report where a PDF can be downloaded.

The machine-readable contract lives at /api/v1/openapi.json. Point your tooling there rather than transcribing this page.

Access

Partner keys are granted to approved partners, and FloodMaps Pro members can create personal keys (see below). To request a partner key, email support@floodmaps.ai describing your application, expected volume, and how end users will reach it.

FloodMaps Pro members

A FloodMaps Pro subscription includes personal API keys for your own tools. Create up to 5 from the API & MCP tab of your dashboard. A personal key acts for your account, so it needs no X-FloodMaps-Subject header.

  • One count: new homes opened through the API or an AI assistant come out of the same monthly addresses as the website. Each home counts once, the first time it's opened anywhere.
  • Explicit unlocks: reads never spend an address. Call POST /properties/{property_id}/unlock to open a new home, then read its report as often as you like. Read-only keys can't unlock.
  • Usage: GET /usage returns the month's addresses by channel, and unlock responses carry FloodMaps-Allowance-Limit, FloodMaps-Allowance-Remaining, and FloodMaps-Allowance-Reset.
  • Fair use: up to 1,000 free summaries a day across the API and assistants.
  • When Pro ends: keys return pro_required until you resubscribe.
Personal key
curl -X POST https://floodmaps.ai/api/v1/properties/{property_id}/unlock \
  -H "Authorization: Bearer fm_live_xxxxxxxxxxxxxxxxxxxx"

Authentication

Every request carries two identities.

  • The partner authenticates with a secret key in the Authorization header.
  • The end user is identified by an opaque value you supply in the X-FloodMaps-Subject header. Send a stable per-user identifier that contains no personal data. Quotas, purchases, and unlocked properties attach to this value, so the same user keeps their reports across sessions.
Headers
Authorization: Bearer fm_live_xxxxxxxxxxxxxxxxxxxx
X-FloodMaps-Subject: user_8f2c1a
Content-Type: application/json

Keys are secrets. Call the API from your server, never from a browser or mobile client.

Coverage

Coverage is regional, and capabilities differ per region. Read GET /coverage at runtime and branch on the advertised capabilities rather than assuming a single market.

  • Greater Houston (tx-houston) — live. Harris, Fort Bend, Montgomery, Galveston, Brazoria counties, TX.
  • Florida (fl) — live. Alachua, Baker, Bay, Bradford, Brevard, Broward, Calhoun, Charlotte, Citrus, Clay, Collier, Columbia, DeSoto, Dixie, Duval, Escambia, Flagler, Franklin, Gadsden, Gilchrist, Glades, Gulf, Hamilton, Hardee, Hendry, Hernando, Highlands, Hillsborough, Holmes, Indian River, Jackson, Jefferson, Lafayette, Lake, Lee, Leon, Levy, Liberty, Madison, Manatee, Marion, Martin, Miami-Dade, Monroe, Nassau, Okaloosa, Okeechobee, Orange, Osceola, Palm Beach, Pasco, Pinellas, Polk, Putnam, St. Johns, St. Lucie, Santa Rosa, Sarasota, Seminole, Sumter, Suwannee, Taylor, Union, Volusia, Wakulla, Walton, Washington counties, FL.

An address outside every live region returns out_of_coverage rather than a guess.

What is free and what is paid

Free, for any resolved property in a live region:

  • Resolved address, coordinates, and coverage region
  • Effective FEMA flood zone and whether it is an SFHA
  • USGS 3DEP ground elevation
  • Whether FEMA draft maps would change the designation, and in which direction
  • A plain-language summary and source attribution

Paid, once the end user unlocks a property:

  • Base flood elevation, freeboard, and modelled flood depth
  • FloodMaps risk score with a factor breakdown
  • Hurricane Harvey modelled damage and FEMA claim history (Greater Houston only)
  • Houston 311 flooding reports nearby (Greater Houston only)
  • Stream gauge history and watershed or channel proximity (Greater Houston only)
  • NOAA Atlas 14 rainfall statistics
  • Parcel records and ground subsidence (Greater Houston only)
  • AI narrative analysis
  • A link to the full interactive report, where the PDF can be downloaded

Typical flow

  1. Resolve the address to a property_id.
  2. Request the free summary and answer the user.
  3. If they want the full picture, request the report. If it is not purchased, you get a 402 carrying a checkout link.
  4. Send the user to that link. Poll the order, or simply retry the report once they confirm payment.

Endpoints

GET/api/v1/coverageNo quota

Supported regions, capabilities, free versus paid breakdown, current limits, and pricing.

POST/api/v1/properties/resolveNo quota

Turns free text into exactly one property. Ambiguous input returns 409 ambiguous_address with candidates so you can ask the user which they meant, rather than risking the wrong house.

Request
POST /api/v1/properties/resolve

{ "address": "5400 Braesvalley Dr, Houston, TX 77096" }
Response
{
  "status": "resolved",
  "property": {
    "property_id": "eyJsIjpbLTk1LjQ2...",
    "address": "5400 Braesvalley Dr, Houston, Texas 77096, United States",
    "short_address": "5400 Braesvalley Dr",
    "coordinates": { "lng": -95.46123, "lat": 29.68451 },
    "zip_code": "77096",
    "coverage": {
      "region_id": "tx-houston",
      "label": "Greater Houston",
      "status": "live",
      "capabilities": ["fema_effective", "fema_draft", "elevation", "..."]
    }
  }
}
GET/api/v1/properties/{property_id}/flood-summaryFree

The free answer. Counts against the end user's daily free lookup allowance.

Response (abridged)
{
  "access": { "tier": "free", "paid_available": true, "unlocked": false },
  "flood_zone": { "zone": "AE", "sfha": true, "label": "AE" },
  "elevation": { "ground_feet": 48.2, "ground_meters": 14.69 },
  "proposed_change": { "differs": true, "direction": "higher_risk", "detail": null },
  "summary_text": "This property is in FEMA flood zone AE, a Special Flood Hazard Area...",
  "data_sources": [
    { "id": "fema_nfhl", "status": "ok", "attribution": "Federal Emergency Management Agency" }
  ],
  "disclaimer": "FloodMaps is an independent service and is not affiliated with FEMA..."
}
GET/api/v1/properties/{property_id}/flood-reportPaid

The full report. When the property is not yet purchased the response is 402 and carries a ready-to-open checkout URL, so you can offer the purchase in a single turn.

402 response
{
  "error": {
    "code": "payment_required",
    "message": "A full flood report for this property has not been purchased yet.",
    "details": {
      "pricing": [{ "tier_id": "single", "name": "1 Report", "price_cents": 700 }],
      "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
      "order_id": "cs_live_...",
      "free_alternative": "GET /api/v1/properties/{property_id}/flood-summary"
    }
  }
}

A successful response includes report_url. That link opens the full interactive report on floodmaps.ai with this property already unlocked, and is safe to hand directly to the end user. PDF generation happens there, in the browser.

POST/api/v1/properties/compareFree

Compares up to 3 addresses and returns plain-language differences. Addresses that cannot be resolved come back in an unresolved list rather than being dropped.

POST/api/v1/checkoutNo quota

Starts a Stripe Checkout session for one property. No FloodMaps account is required to pay. Pass a tier_id from GET /coverage. Use this when the buyer can open a browser. Agents that can complete payment in-session should use the checkout sessions below instead.

Agentic commerce

FloodMaps implements the Agentic Commerce Protocol checkout surface and advertises Stripe Link / Shared Payment Tokens at /.well-known/ucp. The Muse user never pastes a card into chat: the agent creates a session, the buyer approves spend in Link, and the agent completes with a scoped spt_ token. Hosted Checkout at POST /api/v1/checkout remains the browser fallback.

Stripe Agentic Commerce Suite sellers should onboard in the Dashboard, upload the catalog from GET /api/v1/products?format=csv, point the ACS hooks at /api/webhooks/stripe/agentic, and request a connection to each agent. Those hosted checkouts fulfill through the same guest-purchase path as the website.

GET/api/v1/productsNo quota

Sellable SKUs (the same pricing tiers as GET /coverage). Add ?format=csv for a catalog you can upload to Stripe Agentic Commerce Suite.

POST/api/v1/checkout_sessionsNo quota

Create an in-agent checkout. Send a resolved property_id, an item id matching a pricing tier (usually single), and the buyer email.

Create
POST /api/v1/checkout_sessions

{
  "property_id": "eyJsIjpbLTk1LjQ2...",
  "items": [{ "id": "single", "quantity": 1 }],
  "buyer": { "email": "ada@example.com", "first_name": "Ada" }
}
POST/api/v1/checkout_sessions/{id}/completeNo quota

Charge a Stripe Shared Payment Token and unlock the report for this subject. Also accepts the UCP payment.instruments[].credential.token shape from Link Agent Wallet.

Complete
POST /api/v1/checkout_sessions/fmcs_.../complete

{
  "buyer": { "email": "ada@example.com" },
  "payment_data": { "token": "spt_...", "provider": "stripe" }
}
GET/api/v1/orders/{order_id}No quota

Order status. report_url appears once payment settles.

GET/api/v1/entitlementsNo quota

Everything this end user has already unlocked. Check this before prompting for payment.

GET/api/v1/watchesNo quota

Reserved for address-level monitoring of flood map changes. Returns 501 not_implemented today. The contract is published so integrations can be written against a stable shape. Until it ships, poll the free summary and compare proposed_change between calls.

MCP server

AI assistants that speak the Model Context Protocol (ChatGPT, Claude, Muse, and others) can connect to https://floodmaps.ai/api/mcp over Streamable HTTP. It offers the same operations as the REST API as tools, with the same quotas, prices, and disclaimers.

  • Read tools: get_coverage, resolve_address, get_flood_summary, compare_properties, get_flood_report, get_entitlements, and get_order_status.
  • Pro tool: unlock_report opens a new home with one of a FloodMaps Pro member's monthly addresses. The assistant confirms with the user first.
  • Purchase tools: create_checkout_link, start_agentic_checkout, complete_agentic_checkout, and cancel_agentic_checkout. The assistant shows the exact price and terms and needs the user's approval before any charge. Retrying a completed payment never charges twice.

Lookups work without signing in. Purchases need either a FloodMaps account connected through OAuth 2.1 (discovery at /.well-known/oauth-protected-resource/api/mcp) or an approved partner key with a per-user subject. A connected account shares reports bought on floodmaps.ai, and the user can revoke the connection at any time.

Errors

Every error uses the same envelope, so you can branch on error.code rather than parsing prose.

{ "error": { "code": "out_of_coverage", "message": "...", "details": { } } }
  • unauthorized (401) — missing or invalid key
  • forbidden (403) — key lacks the required scope, or is suspended
  • invalid_request (400) — malformed input or an expired property_id
  • payment_required (402) — report not purchased; includes a checkout link
  • allowance_exhausted (402) — a Pro member's monthly addresses are used; includes resets_at
  • pro_required (403) — the FloodMaps Pro plan has ended; includes resubscribe_url
  • ambiguous_address (409) — several matches; ask the user to clarify
  • out_of_coverage (404) — outside every live region
  • rate_limited (429) — honour Retry-After
  • not_implemented (501) — reserved endpoint
  • upstream_unavailable (502) / service_unavailable (503) — retry shortly

Rate limits and quotas

  • Per end user: 25 free lookups per day by default
  • Per key: a short-window burst limit and a daily ceiling, both set per partner

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 also carries Retry-After in seconds.

Partial data

Flood data is assembled from several public sources. When one is slow or unavailable, the affected field is null and data_sources records the outcome for every source, including not_supported for layers a region does not offer. Surface this to users rather than implying complete coverage.

Attribution and appropriate use

Every response includes a disclaimer field. Display or relay it. Summaries, reports, and comparisons also carry an attribution field: wherever you show the data, credit it as “Flood data by FloodMaps” with a link to floodmaps.ai. FloodMaps is an independent service and is not affiliated with FEMA, NOAA, HCFCD, or any government agency. Responses are informational, are not official flood determinations, elevation certificates, or surveys, and must never be used for life-safety or evacuation decisions during an active weather event.

Use is governed by the Terms of Service, including the section on automated and programmatic access, the Privacy Policy, and the Legal Disclaimers. Bulk extraction, resale of raw data, competing products, and use of FloodMaps output to train machine-learning models are prohibited.

Roadmap

  • More states along the Gulf and Atlantic coasts
  • Address-level watches for flood map changes
  • Account linking for partner-key integrations, so their purchases and floodmaps.ai purchases resolve to one entitlement (OAuth connections already do)

Support

Questions, key requests, and integration reviews: support@floodmaps.ai.