Migrating to the modern Static Tiles API

If you are using a custom classic style that you created in Studio Classic and want to migrate to the modern Static Tiles API, you will need to create a new custom style with Mapbox Studio. You can then update your Leaflet or Mapbox.js implementation with your new style ID following the guidance on this page. To understand how this migration will affect your pricing, please refer to our Pricing by products page.

Implications of tile size when using the Static Tiles API

Some mapping libraries, such as Leaflet, are built around map tiles that cover a particular geographic area at a given zoom. The Static Tiles API, by default, serves tiles that each cover an area four times as large as those served by the Raster Tiles API. To support libraries that expect smaller tiles, the Static Tiles API can serve tiles of both kinds, but each tile is priced at the same level. While the Static Tiles API does support requesting tiles that cover a smaller geographic area (using the optional tileSize parameter), using this tile size in your implementation will cause you to request four times more tiles. You can refer to the Accounts and pricing page to compare the number of tiles requested when using the Static Tiles API versus the Raster Tiles API.

If possible, we recommend that you avoid specifying a tileSize of 256 pixels in your client-side implementation to prevent unnecessarily high request volume.

How to tell if you're using a classic style

Start by understanding which tileset IDs are being used by your account. Then, determine if those tileset IDs are associated with classic styles.

Find tileset IDs used by your account

Every classic style has a unique tileset ID, but not every tileset ID references a classic style. Tileset IDs are used for other kinds of raster tilesets (like satellite imagery) and vector tilesets in addition to classic styles.

Check your application's code

If you have access to the source code (or webpages) for all applications using your Mapbox access token, you can check the code directly to identify which tileset IDs are being used.

Find the source code on a webpage

If you don't have access to the source code, you can use your browser's developer tools to dig into the code:

  1. Open the webpage in a browser.
  2. Open the browser's developer tools (if you're not sure how, see the Chrome docs, Firefox docs, Safari docs, or Internet Explorer docs).

In your source code (or in your browser's developer tools window):

  1. Search for your username and look for any references in the format YOUR_USERNAME.SOME_STRING. These are custom tileset IDs that might be associated with custom classic styles from your account.
  2. Search for mapbox. and look for any references in the format mapbox.SOME_STRING. These are Mapbox tilesets IDs that might be associated with classic styles.

If your code includes a style URL (which may be formatted as YOUR_USERNAME/SOME_STRING or mapbox/SOME_STRING) then you're using a modern style and there is no action you need to take.

Check stats in your account

If you're not sure where your Mapbox access token is being used, you can check your stats page to see which tileset IDs are being used by your account:

  1. Log into Mapbox and go to your Statistics page.
  2. Find the Raster Tiles API section.
  3. Toggle the tileset_id option from the dropdown menu.

There you will see all the tileset IDs from both classic styles and raster tilesets (for example, imagery) used by your account.

Determine if a tileset ID is associated with a classic style

Once you've identified which tileset IDs are being used by your account, you can use the following strategies to determine if each tileset ID is associated with a classic style.

Check the list of common classic styles

There are several Mapbox-designed classic styles you may be using in your application. All these styles will be deprecated:

  • mapbox.streets
  • mapbox.light
  • mapbox.dark
  • mapbox.streets-satellite
  • mapbox.outdoors
  • mapbox.streets-basic
  • mapbox.wheatpaste
  • mapbox.comic
  • mapbox.pencil
  • mapbox.pirates
  • mapbox.emerald
  • mapbox.high-contrast
Check your account for custom classic styles

You can see a list of custom classic styles (created in Studio Classic) and classic projects (created in Mapbox Editor) associated with your account here:

All these styles and projects will be deprecated. If you know the style in this list is actively being used in your application, you will need to create a new custom style with Mapbox Studio.

How to update a classic style in modern Mapbox Studio

Learn how to modernize a classic style by recreating it in Mapbox Studio. The new style will adhere to the Mapbox GL JS style specification.

Leaflet implementations

If you are using Leaflet with a Studio Classic template style (for example, mapbox.streets), use the modern equivalent template style with the Mapbox Static Tiles API when initializing the tileLayer. This only requires changing a few lines of code.

var map ='map');
L.tileLayer('{id}/tiles/{z}/{x}/{y}?access_token={accessToken}', {
attribution: '© <a href="">Mapbox</a> © <a href="">OpenStreetMap</a> <strong><a href="" target="_blank">Improve this map</a></strong>',
tileSize: 512,
maxZoom: 18,
zoomOffset: -1,
id: 'mapbox/streets-v11',

By default the modern Static Tiles API returns a 512x512 map tile, instead of the 256x256 that classic styles returned. If you do not include the tileSize: 512 and zoomOffset: -1 options, your map will load but labels, icons, and other features may appear much smaller than expected.

Mapbox.js implementations

Because Mapbox.js is a plugin for Leaflet, the migration pattern is similar. Rather than passing the string id of Mapbox template style (for example, 'mapbox.streets'), you will initialize a styleLayer and add this layer to your map.

L.mapbox.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
var map ='map')
.setView([40, -74.50], 9)
Was this page helpful?