# ADR-004: Maps Strategy — Google Primary, TomTom for Traffic/Matrix/Truck + Auto-Failover

## Status

Accepted, 2026-06-25.

## Status History

```yaml
status_history:
  - date: 2026-06-25
    status: Proposed
    changed_by: hkl
    reason: Formalising vendor strategy already implemented via shared/maps-client.js
    changed_via: adr-kit (360lm)
  - date: 2026-06-25
    status: Accepted
    changed_by: hkl
    reason: Dual-provider helper live; tour-pg + tour-planner use it
    changed_via: adr-kit (360lm)
```

## Context

360lm PWAs (tour-pg, tour-planner, recce, vehicle) need geocoding, routing, distance matrices, and map display. Google Maps is the most accurate for Indian addresses and has the best geocoding quality for Tier 2/3 cities. However, Google's Distance Matrix API has a 100-element limit per request, does not support truck/HCV routing profiles, and real-time traffic data costs are high at scale. TomTom offers large matrix routing (up to 100×100), truck profiles, and competitive traffic pricing — but geocoding accuracy for Indian addresses is lower than Google.

## Decision

Use Google Maps as the primary provider for geocoding and map display. Use TomTom specifically for: (a) traffic-aware routing, (b) large distance matrices (> 100 elements), (c) truck/HCV routing profiles. All Maps calls MUST go through the shared helper at `/var/www/360lm/shared/maps-client.js`, which implements auto-failover from Google → TomTom when Google returns an error or quota-exceeded response.

**Decision Maker:** hkl

## Alternatives Considered

- **Google only.** Rejected: 100-element matrix limit blocks large tour optimisation batches; no truck profile; traffic costs scale poorly.
- **TomTom only.** Rejected: geocoding accuracy for Indian Tier 2/3 city addresses is noticeably worse than Google; would degrade stop-matching quality in tour-pg.
- **OpenStreetMap / OSRM self-hosted.** Rejected: requires infrastructure to host and maintain tile + routing servers; no real-time traffic; Indian address geocoding requires additional data sources. // ponytail: ceiling=current vendor costs, upgrade trigger=monthly Maps bill > ₹20,000
- **Here Maps.** Rejected: smaller Indian address database; less community support for India-specific routing edge cases.

## Consequences

**Positive:**
- Best-of-both: Google geocoding quality + TomTom's large-matrix and truck capabilities.
- Auto-failover means individual provider outages don't break the product.
- Centralised in one helper — swap providers without touching individual PWAs.

**Negative / Trade-offs:**
- Two API keys to manage and rotate.
- Failover logic adds complexity to the shared helper.
- Billing comes from two vendors — requires monitoring both dashboards.

**Risks and mitigations:**
- Both providers quota-exhausted simultaneously: unlikely given different use cases; mitigated by rate-limiting in maps-client.js.
- API key exposure: keys loaded server-side via proxy where possible; browser-side keys scoped to referrer domain.

## Related Decisions

- None.

## References

- `memory/feedback_maps_provider.md` — original rule capture
- `/var/www/360lm/shared/maps-client.js` — shared helper implementation