FloodMaps Developer API

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

Access is granted to approved partners. There is no self-serve signup today. To request a key, email support@floodmaps.ai describing your application, expected volume, and how end users will reach it.

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.

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.
• Southeast Florida (fl-southeast) — planned, not yet available.

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
• Houston 311 flooding reports nearby
• Stream gauge history and watershed or channel proximity
• NOAA Atlas 14 rainfall statistics
• Parcel records and ground subsidence
• 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

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

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.

POST /api/v1/properties/resolve

{ "address": "5400 Braesvalley Dr, Houston, TX 77096" }

{
  "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", "..."]
    }
  }
}

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

{
  "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..."
}

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.

{
  "error": {
    "code": "payment_required",
    "message": "A full flood report for this property has not been purchased yet.",
    "details": {
      "pricing": [{ "tier_id": "single", "name": "1 Premium Report", "price_cents": 500 }],
      "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.

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.

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.

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

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

POST /api/v1/checkout_sessions

{
  "property_id": "eyJsIjpbLTk1LjQ2...",
  "items": [{ "id": "single", "quantity": 1 }],
  "buyer": { "email": "ada@example.com", "first_name": "Ada" }
}

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.

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

{
  "buyer": { "email": "ada@example.com" },
  "payment_data": { "token": "spt_...", "provider": "stripe" }
}

Order status. report_url appears once payment settles.

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

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.

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
• 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. 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, and use of FloodMaps output to train machine-learning models are prohibited.

Roadmap

• Additional geographies, starting with Southeast Florida
• Address-level watches for flood map changes
• A Model Context Protocol endpoint
• End-user account linking, so purchases made on floodmaps.ai and purchases made through a partner resolve to one entitlement

Support

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