04
Product
16
Backend
09
Auth
12
iOS
07
Infra
02
Real-Time

Use iOS CLGeocoder for location enrichment

ADR-0036 ACCEPTED · 2025-10-02
Use iOS CLGeocoder for location enrichment

Context

Locations need to be more than strings — coordinates, timezone, country code, and locality enable map visualizations, timezone-aware scheduling, and distance calculations. The question is where geocoding should happen.

Backend geocoding means a third-party API (Google, Mapbox) with cost, rate limits, and evaluation overhead. Apple Maps Server API is free (25k calls/day) but requires backend infrastructure. iOS CLGeocoder is on-device, zero cost, no rate limits.

Decision

Use iOS CLGeocoder exclusively for location enrichment. Backend stores minimal Location objects (just rawName). iOS enriches locations when viewing trips and sends the data back via mutation.

User: "Paris for 3 days"
→ GPT-5: AddDestination("Paris", 3)
→ Backend stores: Location { rawName: "Paris", latitude: null, ... }
→ iOS fetches trip, geocodes via CLGeocoder
→ iOS sends mutation with coordinates
→ Backend stores enriched data

Consequences

Zero cost, no rate limits, ship immediately without API evaluation. Data model supports future backend geocoding if needed — when a web client becomes priority, evaluate Apple Maps Server API first (25k free calls/day, same quality as CLGeocoder).

The trade-off is locations remain un-geocoded until iOS views them, and web clients would need separate backend geocoding.