How to migrate/switch from Mapbox to MapTiler

This tutorial shows the process of how to migrate/switch from Mapbox to MapTiler. If you are using Mapbox GL JS in an existing application, it is a straightforward task to update it and incorporate the MapTiler SDK JS.

In the majority of cases, you can easily accomplish this by uninstalling the mapbox-gl package and installing the @maptiler/sdk package within your node packages. Additionally, you may need to modify the CDN links and replace instances of mapboxgl with maptilersdk throughout your TypeScript, JavaScript, and HTML/CSS code.

Next, we will see the main changes that must be made to migrate your application from Mapbox to Maptiler.

Installation

npm uninstall --save mapbox-gl
npm install --save @maptiler/sdk 

<script src='https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css' rel='stylesheet' />

<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.1.0/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.1.0/maptiler-sdk.css" rel="stylesheet" />

Replace mapboxgl with maptilersdk

Look in your application and replace mapboxgl with maptilersdk in your TypeScript, JavaScript and HTML/CSS files. Some examples below

Mapbox GL JS

const map = new mapboxgl.Map({
  ....

const marker = new mapboxgl.Marker()
  ....

MapTiler SDK JS

const map = new maptilersdk.Map({
  ....

const marker = new maptilersdk.Marker()
  ....

Replace the api key or accessToken

Find mapboxgl.accessToken in the code and replace it with maptilersdk.config.apiKey. Replace your Mapbox accessToken with your actual MapTiler API key.

Mapbox GL JS

mapboxgl.accessToken = YOUR_MAPBOX_API_KEY_HERE;

MapTiler SDK JS

maptilersdk.config.apiKey = YOUR_MAPTILER_API_KEY_HERE;

Initialize the web map

Mapbox GL JS

With Mapbox GL JS, you initialize a new map like this:

const map = new mapboxgl.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68 // starting zoom
});

MapTiler SDK JS

You can initialize a map in a similar way using the MapTiler SDK JS

const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS, // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
});

Migrate the basemap styles

You can use the MapTiler service to provide the basemap for your application. There are different Map styles to choose from such as streets, satellite imagery, outdoor, dataviz, OpenStreetMap, etc. Each style offers a range of variants that contain the same level of information and has the same purpose but use different color schemes like dark, light, etc. You can also create and use your custom basemap styles by using the customize tool style editor.

Style equivalence

Checkout the list of MapTiler SDK JS Map styles

Map controls

Zoom and rotate controls

Mapbox GL JS

To display zoom and rotate controls, you must add the NavigationControl to the map.

// Add zoom and rotation controls to the map.
map.addControl(new mapboxgl.NavigationControl());

MapTiler SDK JS

The zoom and rotate controls are displayed by default on the map. So there is no need to add the NavigationControl to the map.

Geolocate control

Mapbox GL JS

To display the GeolocateControl, you must add the control to the map.

// Add geolocate control to the map.
map.addControl(
  new mapboxgl.GeolocateControl({
    positionOptions: {
      enableHighAccuracy: true
    }
  })
);

MapTiler SDK JS

The geolocate control is displayed by default on the map. So there is no need to add the GeolocateControl to the map.

Support for right-to-left languages

Mapbox GL JS

To support right-to-left languages such as Arabic and Hebrew you need to add and use the mapbox-gl-rtl-text plugin.

mapboxgl.setRTLTextPlugin(
  'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js',
  null,
  true // Lazy load the plugin
);

MapTiler SDK JS

Right-to-left languages are supported by default so there is no need to add any plugins.

Change the map’s language

Mapbox GL JS

Change the default map language

By default, Mapbox GL JS will not set a language so that the language of Mapbox tiles will be determined by the vector tile source’s TileJSON. To change the default map language (or initial map language), you have to go into Mapbox Studio and modify the map style. You have to do this for each style.

If you want to force the initial language of the map you can do it in the map constructor.

//change the map language to German
const map = new mapboxgl.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68 // starting zoom
  language: "de"
});

MapTiler SDK JS

Change the default map language

The SDK detects the language of the browser and displays the map in that language. There is no need to modify the style or load any plugin. Check the documentation about languages. If you want to define the initial language of the map, just set the language in the map constructor options.

//change the map language to German
const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS,
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
  language: maptilersdk.Language.GERMAN
});

Add 3D terrain to a map

Mapbox GL JS

To add the 3D terrain to a map you have to first add a data source of type raster-dem and then call the map’s setTerrain function.

To activate and deactivate the terrain dynamically you have to create your own control or add some plugin.

map.on('style.load', () => {
  map.addSource('mapbox-dem', {
    'type': 'raster-dem',
    'url': 'mapbox://mapbox.mapbox-terrain-dem-v1',
    'tileSize': 512,
    'maxzoom': 14
  });
  // add the DEM source as a terrain layer with exaggerated height
  map.setTerrain({ 'source': 'mapbox-dem', 'exaggeration': 1.5 });
});

MapTiler SDK JS

To add the 3D terrain to a map just set the terrain: true in the map constructor options. To activate and deactivate the terrain dynamically add the terrainControl: true in the map constructor options. There’s no need to add a data source, add some plugin or create your own terrain control.

//add the 3D terrain and the terrainControl
const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS,
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
  terrain: true, 
  terrainControl: true,
});

Geocoding control

How to easily switch to MapTiler Geocoding from any other provider.

Mapbox GL JS

<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>

// Add the control to the map.
map.addControl(
    new MapboxGeocoder({
        accessToken: mapboxgl.accessToken,
        mapboxgl: mapboxgl
    })
);

MapTiler SDK JS

Check out the MapTiler Geocoding control documentation to see all the usage options such as React, Svelte, MapLibre, etc.

<script src="https://cdn.maptiler.com/maptiler-geocoding-control/v3.0.0/maptilersdk.umd.js"></script>
<link href="https://cdn.maptiler.com/maptiler-geocoding-control/v3.0.0/style.css" rel="stylesheet">

// Add the control to the map.
const gc = new maptilersdkMaptilerGeocoder.GeocodingControl();
map.addControl(gc);

Geocoding API

Mapbox

Check out the official Mapbox Geocoding API documentation to see all the options.

Forward

Reverse

MapTiler

Check out the official MapTiler Geocoding API documentation to see all the options.

Forward

Reverse

Related examples

Switch from MapLibre

Tutorials

Steps to switch from MapLibre GL JS to MapTiler SDK.

Weather layer switcher

Examples

Switch weather layers and view detailed data under cursors.

Start with AR maps

Examples

Add an AR control button to map 3D viewports.

Learn the basics

Tutorials

This tutorial shows how to create a map and display it on a web page using MapTiler.