Levee

Open-source flood zone determination and life-of-loan monitoring, built on free public FEMA data.

Every U.S. lender that makes, renews or buys a loan secured by a building must determine whether the building is in a FEMA Special Flood Hazard Area (SFHA), record the result on the federal Standard Flood Hazard Determination Form (SFHDF), and require flood insurance if it is. Most lenders also pay to have each loan watched until payoff, so they hear when FEMA redraws the map or the town drops out of the National Flood Insurance Program.

That work is sold per loan by a handful of vendors (ServiceLink National Flood, ICE Flood, Unitas360, LERETA and others), and all of it comes from public FEMA data. Levee does the same work in the open: a single static binary, an HTTP API, a CLI and one SQLite file. No API keys, no accounts, no per-loan fees.

$ levee determine "1901 Convention Center Dr, Miami Beach, FL 33139"
Location         1901 CONVENTION CENTER DR, MIAMI BEACH, FL, 33139 (25.794998, -80.134876)
In SFHA          YES - in a Special Flood Hazard Area (flood insurance required)
Flood zone       AE
                 AE, base flood elevation 8.0 ft NGVD29
FIRM panel       12086C0317L effective 09/11/2009
Community        120651 MIAMI BEACH, CITY OF, FL - Participating (Regular Program)
Flood insurance  available (Regular Program)

Review:
  [INFO] GEOCODE_INTERPOLATED: Location is interpolated along the street segment, not a surveyed building footprint.
  [INFO] PENDING_MAP: A new FEMA map (DFIRM 12086C) is pending, effective 02/19/2027.

Levee is a compliance aid, not a guaranteed determination. FEMA's SFHDF instructions accept a determination made by anyone other than the lender only to the extent its accuracy is guaranteed. Levee guarantees nothing. It is built for lenders making their own determinations, for second opinions on vendor certificates, and for monitoring. Every result lists the reasons it needs a human, and those must be reviewed.

What it does

  • Determination. Takes an address or coordinates and returns the flood zone, SFHA status, FIRM panel and effective date, any effective LOMRs, NFIP community (name, county, CID), participation status and program, and Coastal Barrier Resources System status. Each answer comes with machine-readable review flags.
  • SFHDF PDF. Fills every field of the federal form (FEMA Form FF-206-FY-21-116 layout). An attachment page lists the evidence, review items, data sources and the record's audit hash.
  • Portfolio import. Reads a CSV of loans and geocodes street addresses in one Census batch call.
  • Life-of-loan monitoring. Each pass re-checks the loans affected by:
    • changes in the NFIP Community Status Book: participation, suspension, withdrawal, Emergency → Regular program, a new effective map date;
    • newly published Letters of Map Revision covering a loan;
    • FIRM panels that were revised or superseded (physical map revisions);
    • newly published pending maps (adopted but not yet effective), so you can plan borrower notices before a building moves into an SFHA;
    • a scheduled full re-check of every loan (default every 30 days).
  • Events and webhooks. Material changes become events (SFHA_ENTERED, INSURANCE_UNAVAILABLE, ...), delivered in order to your webhook and signed with HMAC-SHA256.
  • Tamper-evident history. Every determination is appended to a hash chain; levee verify detects any edited, deleted or reordered record.

Quick start

Requires Go 1.26+.

make build
./levee determine "1600 Pennsylvania Ave NW, Washington, DC 20500"
./levee determine --lat 29.6970 --lon -95.3920 --pdf sfhdf.pdf

./levee import examples/loans.csv     # 10 demo loans (public buildings)
./levee loans
./levee sfhdf DEMO-002 -o demo-002.pdf
./levee monitor                       # one monitoring pass; add --every 24h to loop
./levee events
./levee verify

./levee serve                         # web UI + API on http://127.0.0.1:8080

With Docker:

docker build -t levee .
docker run -p 8080:8080 -v levee-data:/data -e LEVEE_API_TOKEN=change-me levee

The container runs serve --monitor-every 24h and keeps its database in /data.

Configuration

Setting Flag / env Default
Database path --db / LEVEE_DB levee.db
Listen address serve --addr / LEVEE_ADDR 127.0.0.1:8080
API token for portfolio endpoints LEVEE_API_TOKEN none (open)
Webhook URL / signing secret LEVEE_WEBHOOK_URL, LEVEE_WEBHOOK_SECRET none
Preparer shown on the SFHDF LEVEE_PREPARER_NAME, _ADDRESS, _PHONE "Lender self-determination"
Request rate to FEMA/USFWS --rate 4 req/s
Re-check interval --max-age 720h (30 days)
Parallel determinations --concurrency 2

Loan data is sensitive. The server binds to localhost by default and logs a warning if it is exposed without LEVEE_API_TOKEN. The ad-hoc /v1/determine endpoints stay public and store nothing.

Loan CSV

A header row is required; column order does not matter.

Column Notes
loan_number Re-importing the same number updates the loan in place.
street, city, state, zip Preferred; these are batch-geocoded.
address Alternative one-line address.
lat, lon Optional; skips geocoding (use surveyed coordinates when you have them).
lender_name, lender_address, lender_id, amount_required Printed on the SFHDF.

HTTP API

Method & path Auth Purpose
GET /v1/determine?address=… or ?lat=…&lon=… public Ad-hoc determination (JSON, not stored)
GET /v1/determine.pdf?… public Ad-hoc SFHDF PDF
POST /v1/loans token Add one loan object or {"loans":[…]}; ≤25 determined synchronously
POST /v1/loans/import token CSV body; imported in the background
GET /v1/loans?sfha=true&review=true token List loans with current state
GET /v1/loans/{id or loan_number} token One loan
DELETE /v1/loans/{id} token Stop monitoring (history is kept)
POST /v1/loans/{id}/determine token Force a re-check
GET /v1/loans/{id}/determination · /history · /sfhdf.pdf token Latest, all versions, form
GET /v1/events?since=ID&loan=ID token Event feed (poll with next_since)
POST /v1/monitor/run · GET /v1/monitor token Start a pass / last report
GET /v1/summary · GET /v1/audit/verify token Portfolio counts / chain check

Portfolio endpoints take Authorization: Bearer $LEVEE_API_TOKEN.

Events

Kind Severity Meaning
SFHA_ENTERED critical Building is now in an SFHA. Notify the borrower; force-place coverage if it is not obtained within 45 days (42 U.S.C. 4012a(e)).
INSURANCE_UNAVAILABLE critical Community suspended, withdrawn or non-participating; NFIP policies cannot be renewed.
COMMUNITY_STATUS_CHANGED critical/info Any participation or program change.
SFHA_EXITED info Building left the SFHA; mandatory purchase no longer applies.
ZONE_CHANGED warning Zone changed without crossing the SFHA line (e.g. AE → VE, X → D).
LOMR_EFFECTIVE warning A new Letter of Map Revision covers the building.
PENDING_SFHA warning A pending map will put the building in an SFHA.
PANEL_REVISED info FIRM panel number or date changed.
LOMA_NEARBY info FEMA issued a LOMA/LOMR-F within 40 m; obtain the letter.
CBRS_CHANGED, PENDING_MAP, PENDING_CLEARED, INSURANCE_AVAILABLE warning/info As named.

Webhook requests carry X-Levee-Event, X-Levee-Delivery and X-Levee-Signature: sha256=<hex HMAC-SHA256 of the body with LEVEE_WEBHOOK_SECRET>. Events are delivered in order. Delivery pauses at the first failure and resumes on the next pass, with up to 10 attempts per event.

Review flags

Levee never guesses. When public data cannot support a clean answer, it says so:

Flag Severity Why
GEOCODE_INEXACT, GEOCODE_AMBIGUOUS warn The geocoder changed the house number or ZIP, or returned several candidates.
NEAR_SFHA warn An SFHA lies within 30 m of the point. The whole building is in the SFHA if any part of it is.
ZONE_BOUNDARY, MULTIPLE_PANELS, MULTIPLE_JURISDICTIONS warn The point sits on a boundary.
PAPER_MAP block FEMA has no digital data here, but the community has an effective (paper) FIRM.
NO_ZONE_POLYGON, AREA_NOT_INCLUDED, OPEN_WATER, NO_COMMUNITY block The map can't be read automatically at this point.
CBRS / CBRS_BOUNDARY block / warn Coastal Barrier Resources System: federal flood insurance is prohibited for buildings built or substantially improved after the unit's date.
SOURCE_CONFLICT warn FEMA's own datasets disagree (e.g. the Status Book says "no SFHA" but the map shows AE).
LOMA_NEARBY warn A nearby LOMA may remove the building from the SFHA; get the letter.
PENDING_SFHA warn An adopted map will change the answer on a known date.
SFHA_NO_INSURANCE, COMMUNITY_NOT_PARTICIPATING warn Federal flood insurance is unavailable.
ZONE_D, NO_NFIP_MAP, DATA_UNAVAILABLE warn Undetermined hazard, no map, or a data source failed during this run.

Data sources (all public, no keys)

Source Used for
FEMA National Flood Hazard Layer Flood zones, FIRM panels, LOMRs, LOMAs, political jurisdictions, digital coverage
FEMA NFHL pending data Adopted maps that are not yet effective
OpenFEMA NFIP Community Status Book Participation, program, sanctions, effective map dates
USFWS Coastal Barrier Resources System CBRS / OPA prohibition areas and dates
U.S. Census Geocoder Address → coordinates (one-line and batch)

FEMA's map server is slow and returns intermittent 504s, empty bodies and truncated JSON, and its firewall rejects POST requests. Levee therefore sends only GET requests, splits long IN (...) queries, rate-limits itself, and retries transient failures with backoff. Monitoring is built around the changes FEMA actually publishes (LOMR dates, panel suffixes and dates, Status Book fields, pending-study footprints). It does not repeatedly re-query the whole portfolio.

Known limitations

  • Geocoding is street interpolation, not rooftop. Supply lat/lon from a survey or parcel centroid when you have one; NEAR_SFHA exists because of this.
  • Buildings, not points. Levee tests one point per loan. Multi-building collateral and large parcels need one row per building.
  • Paper-only maps (communities without digital NFHL coverage) are flagged, not determined.
  • LOMAs are reported for review but never applied automatically: the letter itself governs.
  • No guarantee or indemnity. That is the main thing vendors sell beyond the data.
  • The Dockerfile has not been tested in CI. The static binary it builds has been.

Development

make test   # unit tests, no network
make live   # integration tests against the real FEMA/USFWS/Census services (LEVEE_LIVE=1)
make vet

The code lives under internal/:

Package Role
arcgis Defensive ArcGIS REST client
fema NFHL, pending maps, Community Status Book, CBRS
geocode Census geocoder
determine Determination engine and change diffs
store SQLite storage and hash chain
monitor Monitoring passes and CSV import
sfhdf Dependency-free PDF writer and form layout
api HTTP server and UI
webhook Event delivery

License

MIT. Not affiliated with or endorsed by FEMA, DHS, USFWS or the Census Bureau.

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support