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 verifydetects 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/lonfrom a survey or parcel centroid when you have one;NEAR_SFHAexists 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.