Search NFIP Flood Insurance Claims
fema_search_nfipRead-only
Search National Flood Insurance Program (NFIP) claims data by state, county, ZIP code, and year range. Returns the matching claim count and claim records — amounts paid on building and contents, damage estimates, flood zones, cause and occupancy codes, and loss dates — newest loss first. state is required — the full NFIP dataset is 2.7 million rows; unfiltered access is prohibited. Page the inline claims with limit and offset; a page holds at most 100,000 characters of claims, and while claims remain past it, next_offset is the offset to continue from. When DataCanvas is enabled and the match exceeds that inline budget, a call at offset 0 stages the match (up to 50,000 claims) on a canvas: inspect the staged table with fema_dataframe_describe, then aggregate it with SQL via fema_dataframe_query.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum claims to return inline (1–10000, default 1000). A page also stops at 100,000 characters of claims (roughly 330 claims); when either bound leaves matching claims out, next_offset names the offset to continue from. When DataCanvas is enabled and the match exceeds that character budget, a call at offset 0 stages the match on a canvas regardless of this value. | |
| state | Yes | Two-letter US state code (required). NFIP dataset is 2.7M rows — state filter is mandatory. | |
| offset | No | Pagination offset into the matching claims, ordered newest date of loss first (default 0). Pass the previous page’s next_offset to continue. Only a call at offset 0 stages a match on a canvas; a later offset returns just its inline page. After a spill (spilled=true), read rows past the inline claims from the canvas table with fema_dataframe_query. | |
| year_to | No | End year of loss, inclusive (e.g., 2023). Equal to year_from for a single year. | |
| zip_code | No | ZIP code to narrow results to a specific area (5-digit, e.g., 77002). | |
| canvas_id | No | Optional canvas ID from a prior call, to stage this match as another table on that canvas. Used only when the match is staged; omit it to stage on a fresh canvas. Pass the returned canvas_id to fema_dataframe_describe for the table columns, then to fema_dataframe_query for SQL. | |
| year_from | No | Start year of loss, inclusive (e.g., 2020). Not after year_to. | |
| county_code | No | County FIPS code to narrow results within the state: the full 5-digit state+county code (e.g., 48201 for Harris County TX), or the 3-digit county part (e.g., 201), to which the server prepends the state FIPS. A shorter county part is zero-padded to 3 digits (1 → 001), and a 4-digit code is zero-padded to 5 (1001 → 01001), the form a numeric 01001 arrives in. Any other value is rejected before the search runs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| claims | No | Claims from offset onward, newest date of loss first, bounded by limit and 100,000 characters of claims. When spilled=true, canvas_table holds the staged match. | |
| notice | No | Zero-match, paging, and canvas guidance, composed with county-coverage disclosure: a state/year count of claims without county codes when already available, or an unchecked-coverage notice; this count does not identify any county or ZIP. | |
| spilled | No | True when the match exceeded the inline budget and was staged on DataCanvas: call fema_dataframe_describe, then fema_dataframe_query, with canvas_id. False when nothing was staged. | |
| canvas_id | No | Canvas ID for the staged match. Pass to fema_dataframe_describe and fema_dataframe_query. Present only when spilled=true. | |
| truncated | No | True when the 50,000-row canvas cap was reached: canvas_table holds staged_count of the total_count matching claims. Apply tighter filters (county_code, zip_code, year range) to stage the complete set. | |
| next_offset | No | Offset of the next inline page: offset plus returned_count. Present only while matching claims remain past this page, after a spill too; pass it as offset to continue. | |
| total_count | No | Claims matching the filters, as counted by OpenFEMA — before offset, limit, and the canvas row cap. | |
| canvas_table | No | DuckDB table on the canvas holding the staged claims. List its columns with fema_dataframe_describe, then reference it in fema_dataframe_query FROM clauses. Present only when spilled=true. | |
| staged_count | No | Claims staged on canvas_table: the whole match, or its first 50,000 when truncated=true. Present only when spilled=true. | |
| returned_count | No | Number of claim records in claims. |