Azure Maps (geocoding)

Contacts and event venues are geocoded with the Azure Maps Search API so the admin app can plot them, assign them to regions and areas, and target campaigns by distance.

Code	crm/geocoding.py, crm/geo.py (regions, areas, polygon containment, saved shapes), crm/geography_runs.py, tasks geocode_contact, geocode_event, run_geography_assign
Runbook	crm/README.md (Geocoding, Geographic targeting)
Env	AZURE_MAPS_KEY, GEOCODING_ENABLED (defaults on when the key is set), GEOGRAPHY_ASSIGN_SYNC_MAX (default 1000), GEOGRAPHY_RUN_STALE_MINUTES (default 30)

When geocoding runs

Trigger	Task
Contact created or address changed (including a paid order, registration or donation replacing the billing address)	geocode_contact, then region/area re-assignment
Event venue saved	geocode_event
Staff "Geocode" action on a contact	POST /rest/crm/contacts/<id>/geocode/
Backfill	manage.py geocode_contacts

Regions and areas

Region and Area are polygons drawn in the admin app's Geography page (Leaflet + Geoman). Assigning contacts to them is a point-in-polygon pass:

• Small scans run synchronously (GEOGRAPHY_ASSIGN_SYNC_MAX).
• Larger ones become a GeographyAssignRun executed by run_geography_assign and polled by the admin app at /rest/crm/contacts/assign-geography/runs/<uuid>/. Runs older than GEOGRAPHY_RUN_STALE_MINUTES are treated as stale.

The map's geo-sales layer (/rest/crm/contacts/geo-sales/) uses the same coordinates to show book purchases by location.

Privacy

Coordinates are stored on the contact; the map endpoints return only ids and points within the caller's scope (scope_contacts()), never bulk personal data.

note

GEOGRAPHY_ASSIGN_SYNC_MAX and GEOGRAPHY_RUN_STALE_MINUTES are not in the compose x-app-env anchor yet.