Migration

Moving off Mapbox static maps and tiles for geocoding-only use

Mapbox is often adopted as a package deal: geocoding, static map images, vector tiles, and the Mapbox GL rendering library, all under one access token and one account. That bundling makes sense when a project needs a full mapping stack, but it complicates a narrower migration, because a team that only wants to change its geocoding provider may find the geocoding call and the map rendering code sharing configuration, tokens, or even the same request wrapper function.

The first real step in this kind of migration is not technical, it is scoping. Deciding explicitly that map tiles and static map images stay on Mapbox while only the geocoding call moves elsewhere avoids a common failure mode: starting a migration with an unclear boundary and ending up half-changing code that touches both concerns at once.

My Geocode is a geocoding, IP, timezone, elevation, and postal code lookup API. It does not render map tiles or static map images, so it is not a replacement for that part of a Mapbox integration, only for the address lookup piece. Its Mapbox compatibility host reproduces the GeoJSON FeatureCollection structure that Mapbox Geocoding returns, including center, place_name, and context fields, with the copyright, terms, and privacy text as the only difference. Reference details are at /compatibility/mapbox/.

Practical separation steps:

  • Find every place in the codebase where a Mapbox access token is read, and determine whether that specific call site does geocoding, tile rendering, or both, since some wrapper functions historically combine address lookup with a map preview in one call
  • Move the geocoding-specific calls to use a distinct key from a distinct host, while leaving the tile and static map calls pointed at Mapbox with their existing token unchanged
  • Confirm the front-end map component does not assume the geocoding result and the map tiles come from the same coordinate reference or projection convention, since this is rarely an issue but worth a quick check

Authentication for the geocoding compatibility host works with a key as X-API-Key, Authorization: Bearer, HTTP Basic auth, or a query parameter. There are 2,500 free requests a day with no key, another 2,500 free per key per day counted per network, then prepaid credit at €0.0001 per request or an Unlimited key at €50 a month, the same rate applied to every endpoint including this one.

Running two providers side by side, one for map rendering and one for address lookup, is a stable long-term setup rather than a temporary state to eliminate. Plenty of production applications split mapping and geocoding across different vendors deliberately, since the two capabilities have different cost drivers and different technical requirements, and there is no obligation to consolidate them under a single account just because they started that way.