# Explore Uganda — Google Maps integration

## Temporary testing configuration
The owner-supplied browser key and map ID are temporarily embedded in `app/api/maps-config/route.ts`. Maps and Places default to enabled. Explicit runtime variables take precedence, including `GOOGLE_MAPS_ENABLED=false` to disable maps. Remove the two TEST constants and restore empty/disabled defaults after moving to runtime configuration. The testing key is included in source downloads as explicitly requested; Google API enablement, billing and website restrictions still apply. Live Google behavior has not been verified by this configuration-only update.


## What changed
The shared map adapter replaces the schematic SVG. Public `/map` includes module, category, region and text filters, selected records, clustered Advanced Markers and explicit “Search this map area”. Catalogue map links preserve their filters. Destination, accommodation, tour, event, marketplace and emergency detail pages share location summaries and maps when physical coordinates exist. The planner shows mapped destination references; it does not claim road routes or travel times.

All location forms use the same address, purpose, nullable coordinates, accuracy and sample fields. Configured Google Places (New) search and map click/drag can set a pin. Search is limited to Uganda. Coordinates can always be entered or removed manually. Marketplace pins must represent a seller outlet or collection point, tours a meeting point, and events a physical venue. Emergency service coverage remains independent of the physical service point.

## Enable Google Maps
Configure these values in the existing Site runtime environment settings:

| Variable | Value |
| --- | --- |
| GOOGLE_MAPS_BROWSER_KEY | A Google browser API key restricted to the actual Site origin and required APIs |
| GOOGLE_MAPS_MAP_ID | Your Google Maps JavaScript map ID |
| GOOGLE_MAPS_ENABLED | true |
| GOOGLE_MAPS_PLACES_ENABLED | true only when Places API (New) is enabled |

Enable billing and Maps JavaScript API in the owning Google Cloud project. Enable Places API (New) for admin place search. No Geocoding or Routes API is required for this release. Use separate production and development keys. Add only the specific development origins you use to the development key's website restrictions. Never put a server key in these browser settings. The browser key is intentionally returned to the browser by `/api/maps-config`; referrer and API restrictions are essential. This endpoint returns no other environment variables.

For local Vinext/Wrangler development, copy the variable names from `.env.example` into an ignored `.dev.vars` file. Keep secrets out of Git. Both `.env*` (except the blank example) and `.dev.vars*` are excluded from the downloadable source package.

Set quotas and billing alerts in Google Cloud. Budget alerts do not impose a spending cap. The singleton loader avoids repeat script loads within a page, and Google Places requests only a location and place ID. Do not enable unnecessary APIs.

Optional map colours are configured against the map ID in Google Cloud. Keep labels, roads, landmarks and Google attribution legible. The application uses green markers and yellow selected markers with red accents.

## Location governance
`mapLocation` is additive: existing browser data is not reset. Legacy destination coordinates are approximate references and never become verified automatically. Fictional offers retain their old fields for compatibility but do not inherit map pins from destination centres. An absent pin does not hide a valid directory entry.

Location verification uses the `locations.verify` permission with existing organisation, region and category scopes. Assign it to an appropriate role through User Management. No existing role receives broader grants automatically; the existing recovery administrator retains its wildcard. A record must be Approved or Published and genuinely located with entrance/exact accuracy. The configured separation-of-duties policy applies. Evidence and actor are audited, revisions are checked, and edits reset location verification. Emergency contact-information verification remains a separate workflow.

Directions use Google Maps URLs only for precise, verified, non-sample physical locations. Sample emergency communication and directions remain disabled. Approximate park centres are not visitor entrances.

Places-derived coordinates carry a retrieval timestamp. They expire after 29 days and are cleared when browser data is loaded; expired coordinates are also suppressed by location reads. Place IDs can remain for a fresh lookup. Google-formatted addresses and other Place content are not persisted by autocomplete; the address field is supplied by the operator. Recheck current Google terms before production storage or adding geocoding, routing or place-content caching.

## Resilience and rollback
Without configuration, on blocked networks, or after a loading/authorization failure, show an honest map-unavailable message and retry control. Directories, details and manual forms stay usable. Set GOOGLE_MAPS_ENABLED=false to disable live maps without reverting content or changing access controls. No fake basemap or fabricated route estimate is presented.

## Validation and remaining activation checks
Automated service checks cover existing workflows plus coordinate validation, legacy classification, sample-direction suppression, permission and revision guards, verification audit/reset, and Places-coordinate expiry. TypeScript checks and production build are required before publishing.

Browser QA passed for missing-configuration fallback, directory filters, catalogue-to-map navigation and admin manual-location entry/save. The 390px embedded viewport had no material horizontal overflow. All 34 automated checks passed. No Google key was available during implementation, so live tiles, Google authorization failures, Places selection, marker clustering, dragging and map bounds need a final configured-browser check. Road routing/ETA calculation is not implemented; add a server-side Routes API adapter as a separate feature if required, with protected credentials, quotas and supported-region tests.

This remains a browser-local prototype. UI/service permission checks demonstrate policy; trusted server enforcement, persistent database records and tamper-resistant audit storage are required before production administration.

## Official references
- [Maps loading](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
- [Advanced Markers](https://developers.google.com/maps/documentation/javascript/advanced-markers/migration)
- [Places autocomplete](https://developers.google.com/maps/documentation/javascript/place-autocomplete-new)
- [Maps URLs](https://developers.google.com/maps/documentation/urls/get-started)
- [API security](https://developers.google.com/maps/api-security-best-practices)
- [Cost management](https://developers.google.com/maps/billing-and-pricing/manage-costs)
