Create new project design plans

2026-08-28 14:23:26 -07:00
parent a7d6db8177
commit 7ce73f19c5
22 changed files with 2682 additions and 263 deletions
@@ -0,0 +1,70 @@
+# map-checker
+
+Cross-references our Sumter/Lake county address data against a reference map
+(e.g. [thevillages.com/map](https://www.thevillages.com/map/)) to catch city
+boundary or misnaming issues (e.g. addresses that are really in The Villages
+but our data has as Lady Lake, Sumterville, Leesburg, etc.).
+
+## Why this is manual, not automated
+
+thevillages.com's Terms of Use explicitly prohibit automated access:
+
+> "You must not use any robot, spider or other automatic device, process or
+> means to access the Website for any purpose, including monitoring or
+> copying any of the material on the Website."
+
+So this subproject never fetches, scrapes, or otherwise programmatically
+touches their site. Every input here comes from a human looking at the
+official map in their own browser and either tracing a boundary or recording
+an observation by hand.
+
+## Workflow 1: hand-traced boundary (recommended)
+
+Recording individual addresses one at a time doesn't scale to tens of
+thousands of records. Instead, trace the boundary **once** and check every
+address against it in one pass.
+
+1. Open `https://www.thevillages.com/map/` (or another reference map) in one
+   browser tab.
+2. Open **`/map-checker`** in the app (the "Boundary Tracer" link on the main
+   page) in another tab.
+3. Click "New polygon", then click the map to place vertices tracing the
+   boundary you see on the reference map. The Villages is disjoint across
+   three counties, so you'll likely want several separate polygons - just
+   name them all the same (e.g. "The Villages") and add another with "New
+   polygon" once you finish the current one.
+4. Click "Finish polygon", give it a name, repeat for each disjoint piece.
+5. Click "Save to server" (requires login) - this writes
+   `/data/map-checker/boundary.geojson`. "Download GeoJSON" also works if you
+   just want a local copy.
+6. Run the point-in-polygon check:
+
+   ```bash
+   docker compose exec web python3 map-checker/check-boundary.py --county lake --county sumter
+   ```
+
+   This flags:
+   - addresses **inside** the traced boundary whose county/OSM city fields
+     don't say "The Villages" (probably under-tagged), and
+   - addresses **outside** it that do say "The Villages" anyway (probably
+     over-tagged or the boundary needs another pass).
+
+   Pass `--expect-city "Some Other City"` to check a different boundary/name,
+   and `--output flagged.geojson` to save the flagged points for review in
+   the main map viewer.
+
+## Workflow 2: individual spot-checks
+
+For one-off verification of a specific address (not a bulk boundary check),
+[`reference.yml`](reference.yml) + `check.py` still works the same way as
+before: hand-record what the reference map says for a specific street/area,
+then run `python check.py` to compare it against our data. See the comments
+at the top of `reference.yml` for the entry format.
+
+## Scope
+
+`check-boundary.py` is only as accurate as the hand-traced polygon - it's a
+spot-check/audit tool, not a source of truth. For a systematic (but coarser)
+look at where the county's own postal-community and city/jurisdiction fields
+disagree with each other and with OSM, see the "City Boundaries" report in
+the main app (`/reports/city-boundaries`).