Skip to content
Home
Migrate

Migrate to Maptoolkit

These guides are for developers who already have a working map. Each one answers the same three questions in the same order: what does Maptoolkit not do, what does the code change look like, and what will bite you in the first week.

Migrating from Mapbox

Migrating from Mapbox is mostly mechanical. Maptoolkit serves the same kinds of things in the same formats, and MapLibre GL JS is the open fork of Mapbox GL JS, so most application code is unchanged and the basemap is a style URL.

The real work is dropping mapbox-gl for maplibre-gl, and remapping any custom layers written against the Mapbox Streets schema. Anything built on Mapbox Studio or the Tilesets API has no equivalent here at all.

Watch for: terrain is Terrarium encoded where Mapbox is terrain-rgb. A copied source block loads without error and renders noise.

Migrating from Google Maps Platform

Migrating from Google Maps means rewriting the map layer, and usually pays off the most. The Google Maps JavaScript API and MapLibre GL JS share no interface: different coordinate order, different marker and info window model, different event names.

The services map more cleanly than the map does. Directions, Distance Matrix, Geocoding and Elevation all have direct counterparts.

Watch for: Google uses {lat, lng} objects, Maptoolkit and every other library here use [lng, lat] arrays. Places autocomplete, Street View and traffic have no equivalent.

Migrating from MapTiler

Migrating from MapTiler is the closest peer migration, and often comes down to one URL. Both services are MapLibre-native and style-URL driven, so in many cases only the style URL and the key change.

Because the mechanics are so similar, that guide spends most of its length on the differences that actually matter: the cartography, what each service has that the other does not, and where the schemas diverge.

Watch for: MapTiler has satellite imagery and we do not. If your map has an aerial layer, read that section before you start.

Common to every migration

  • An API key replaces whatever token you use today. See First Steps.
  • Attribution is required. Maptoolkit and OpenStreetMap must stay visible on the map. This is a license condition, not a default you can switch off.
  • Errors are plain text, not JSON. A failed request returns an HTTP status with a short text/plain body. Parsing it as JSON will throw.
  • Nothing is billed per map load. Requests are metered, tiles separately from API calls. See the pricing page.