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}/unlockto open a new home, then read its report as often as you like. Read-only keys can't unlock. - Usage:
GET /usagereturns the month's addresses by channel, and unlock responses carryFloodMaps-Allowance-Limit,FloodMaps-Allowance-Remaining, andFloodMaps-Allowance-Reset. - Fair use: up to 1,000 free summaries a day across the API and assistants.
- When Pro ends: keys return
pro_requireduntil you resubscribe.
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
Authorizationheader. - The end user is identified by an opaque value you supply in the
X-FloodMaps-Subjectheader. 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/jsonKeys 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
- Resolve the address to a
property_id. - Request the free summary and answer the user.
- If they want the full picture, request the report. If it is not purchased, you get a
402carrying a checkout link. - Send the user to that link. Poll the order, or simply retry the report once they confirm payment.
Endpoints
/api/v1/coverageNo quotaSupported regions, capabilities, free versus paid breakdown, current limits, and pricing.
/api/v1/properties/resolveNo quotaTurns 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", "..."]
}
}
}/api/v1/properties/{property_id}/flood-summaryFreeThe 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..."
}/api/v1/properties/{property_id}/flood-reportPaidThe 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 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.
/api/v1/properties/compareFreeCompares up to 3 addresses and returns plain-language differences. Addresses that cannot be resolved come back in an unresolved list rather than being dropped.
/api/v1/checkoutNo quotaStarts 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.
/api/v1/productsNo quotaSellable SKUs (the same pricing tiers as GET /coverage). Add ?format=csv for a catalog you can upload to Stripe Agentic Commerce Suite.
/api/v1/checkout_sessionsNo quotaCreate 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" }
}/api/v1/checkout_sessions/{id}/completeNo quotaCharge 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" }
}/api/v1/orders/{order_id}No quotaOrder status. report_url appears once payment settles.
/api/v1/entitlementsNo quotaEverything this end user has already unlocked. Check this before prompting for payment.
/api/v1/watchesNo quotaReserved 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, andget_order_status. - Pro tool:
unlock_reportopens 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, andcancel_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 keyforbidden(403) — key lacks the required scope, or is suspendedinvalid_request(400) — malformed input or an expiredproperty_idpayment_required(402) — report not purchased; includes a checkout linkallowance_exhausted(402) — a Pro member's monthly addresses are used; includesresets_atpro_required(403) — the FloodMaps Pro plan has ended; includesresubscribe_urlambiguous_address(409) — several matches; ask the user to clarifyout_of_coverage(404) — outside every live regionrate_limited(429) — honourRetry-Afternot_implemented(501) — reserved endpointupstream_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.