Migration

Migrating a mobile app's geocoding calls

Migrating geocoding calls made directly from a mobile app introduces a few constraints that a purely server-side migration does not have to deal with, and it is worth naming them clearly before starting, since they change the shape of the plan.

The first is release cadence. A server-side change can go live the moment it is deployed. A mobile app change has to go through app store review, and adoption then depends on users actually updating, which for many apps takes weeks to reach a majority of the installed base and can take considerably longer to reach everyone. Any migration plan for a mobile app needs to account for running two providers, or two versions of the app, side by side for longer than a server migration typically requires.

The second is credential exposure. An API key embedded directly in a mobile app binary is extractable by anyone with the motivation to look, which is a security consideration regardless of which provider is involved. If your current integration calls a geocoding API directly from the client with an embedded key, a migration is a reasonable moment to reconsider that pattern and move the call behind your own backend instead, even though that adds a bit of latency and a bit of backend work.

A few practical steps that apply to most mobile migrations:

  • If moving the call server-side, design the new backend endpoint first and get the mobile app talking to your own API before worrying about which provider sits behind it, decoupling the app-side change from the provider-side change entirely
  • If keeping the call client-side, use a build-time configuration value for the API host and key rather than hardcoding them, so a future migration does not require finding and replacing a literal string across the codebase again
  • Test on actual older app versions still in the wild, not just the latest build, if you plan to support both providers during a transition period, since an old app version calling an old, soon-to-be-retired host is a realistic scenario that deserves an explicit decision about how long to keep supporting it

My Geocode's authentication options, an X-API-Key header, an Authorization: Bearer header, HTTP Basic auth, or a query parameter, work the same whether a request originates from a mobile client directly or from your own backend proxying the call, so this particular decision (client-side versus server-side) does not constrain which authentication style is available either way. Quota usage is visible on every response through headers like X-Quota-Used and X-Quota-Reset, documented at /docs/rate-limits/, which is useful for monitoring a mobile migration's rollout progress if you can access those headers from wherever the requests originate.

Mobile migrations reward patience more than server-side ones do, mostly because the release and adoption cycle imposes a timeline you cannot compress by working faster. Planning for a longer transition window from the start avoids the frustration of expecting a server-side migration's pace from a process that structurally cannot move that fast.