docs/adding-a-region.md

# Adding a New Region (County)

The estimator is region-agnostic: each area you cover is one `RegionConfig` in
`src/lawn_estimator/regions.py` that wires concrete data-source adapters behind
the ports in `src/lawn_estimator/sources/base.py`. Adding a county is finding a
handful of public endpoints and writing a ~20-line `build_<county>()` function —
no core pipeline changes.

Resolution tries each registered region's geocoder in order; the first hit pins
that region for the whole run (falling back to validated Google + parcel-pinning
if no county address layer matches).

---

## What to gather

### Required (4)

| # | Source | What it is / how to find it | Used for |
|---|--------|------------------------------|----------|
| 1 | **Address points** | An Esri `Address_Points`-style FeatureServer/MapServer layer with a full-address field (usually `FULLADDR`). Search the county's ArcGIS portal (`<county>.gov/gis`, `data.<county>...opendata.arcgis.com`). | Free, keyless geocoding that lands *on the building* (so the parcel lookup always hits). Optional — a region can geocode via Google only, but that costs API calls and is less precise. |
| 2 | **Parcels** | An Esri parcel FeatureServer (polygon) supporting point-in-polygon queries (`Query` capability). Plus a **field map**: which attribute is the parcel id, the site address, and year-built (if any). | The legal boundary + the year-built vintage guard. |
| 3 | **LiDAR** | Almost always **USGS via The National Map** — national coverage. Query `tnmaccess.nationalmap.gov/api/v1/products` (`datasets=Lidar Point Cloud (LPC)`, a bbox over the area) and note the dataset title prefix + flight year. A local county LiDAR bucket only if it's newer/denser (e.g. Douglas's 2022). | Ground points → the high-confidence estimate (with imagery-only fallback when absent). |
| 4 | **Local CRS** | The correct UTM zone (EPSG). Eastern Nebraska = `EPSG:26914` (14N); western Iowa / across the Missouri = `EPSG:26915` (15N). | Area math + LiDAR/point projection. |

### Optional (graceful fallback if absent)

| # | Source | Absent → fallback |
|---|--------|-------------------|
| 5 | **Street / road centerlines** (Esri polyline layer) | Street-aware right-of-way extension (Phase 3.5). Absent → extend-all + neighbor subtraction (per-extension sizes still reported so the user can hand-correct). |
| 6 | **Ortho imagery** tile service (county aerials) | Crisp display layer. Absent → visualizations render on Google satellite. |

---

## The two counties we ship today (worked examples)

**Douglas County, NE** (`build_douglas`)
- Address points: `dcgis.org/server/rest/services/vector/Address_Points/FeatureServer/0` (`FULLADDR`)
- Parcels: `dcgis.org/server/rest/services/vector/Parcels_public/FeatureServer/0`
  — field map `{object_id: OBJECTID, site_address: PROPERTY_A, year_built: BLDG_YRBLT, bldg_sqft: BLDG_SF}`
- LiDAR: county 2022 QL1 on public S3 (`DouglasS3LidarSource`, vintage 2022, ~8 pts/m²)
- Streets: `.../vector/Street_Centerlines/FeatureServer/0` · Ortho: 2025 county tiles · CRS: 26914

**Sarpy County, NE** (`build_sarpy`)
- Address points: `geodata.sarpy.gov/arcgis/rest/services/Cadastral/LandRecordsDynamic/MapServer/2` (`FULLADDR`)
- Parcels: `services.arcgis.com/OiG7dbwhQEWoy77N/.../Sarpy_Parcels_WFL1/FeatureServer/0`
  — field map `{object_id: OBJECTID, site_address: SITEADDRESS}` (**no year-built field** → new
  construction rides the RGB-only fallback instead of a vintage warning)
- LiDAR: `UsgsTnmLidarSource(["NE_Eastern_Nebraska_UA_LiDAR_2016"], vintage_year=2016)` (~2 pts/m²)
- Streets: `.../LandRecordsDynamic/MapServer/3` (Road Centerlines) · Ortho: none (Google display) · CRS: 26914

Note how the **field map** absorbs schema differences (Douglas `PROPERTY_A` vs Sarpy
`SITEADDRESS`) so the pipeline only ever sees canonical keys.

---

## Steps

1. **Find endpoints 1–4** on the county's ArcGIS portal (~30 min). Verify the parcel
   layer's `?f=json` shows `"capabilities": "Query"` and lists the fields you'll map.
2. **Confirm LiDAR** with a TNM bbox query over a known address; record the dataset
   prefix + year. (If TNM has nothing, the region still works on RGB-only.)
3. **Write `build_<county>(session, config) -> RegionConfig`** in `regions.py`,
   reusing `EsriAddressPointsGeocoder`, `EsriParcelSource` (with your field map),
   `UsgsTnmLidarSource` (or a county source), and optional streets/ortho.
4. **Append it to `REGION_BUILDERS`.**
5. **Validate (the "quality LOOK"):** run 3–5 known addresses. Confirm they resolve
   to the right region + parcel, LiDAR produces sane ground points (or cleanly falls
   back), and the visualization aligns (red points on roofs, green on lawn). Spot-check
   estimates against the RGB vegetation baseline.
6. **Regression:** re-run the Douglas QA batch — it must stay byte-identical (adding a
   region must never perturb existing ones).

---

## Gotchas learned the hard way

- **Gov ArcGIS servers flake** with transient 5xx. All Esri/TNM queries go through
  `http_get_with_retry`; `resolve_region` degrades to Google on sustained errors.
- **Municipality labels** for unincorporated addresses can be the county name; the
  geocoder prefers the city the user typed.
- **Attached housing** (duplex/townhome) has one parcel *per unit* — measuring only
  the queried address's parcel is correct, not a bug.
- **LiDAR vintage is per-source**, not per-region — a newer flight is a one-line swap.
- **UTM zone**: crossing the Missouri into Iowa means `EPSG:26915`, not 26914.