# 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`).