Migrating to the modern Static Tiles API

Mapbox classic styles are no longer supported and cannot be requested. If your application still references a custom classic style created with Mapbox Studio Classic, you must update the application to use a modern Mapbox style and the modern Mapbox Static Tiles API. Benefits to migrating to a modern Mapbox style include:

• Frequent data updates for Mapbox vector tiles
• The ability to customize and style your maps with style components in Mapbox Studio
• Significantly improved load times and global reliability

To recreate your classic style with up-to-date Mapbox tools, you will need to create a new custom style with Mapbox Studio. Once you decide which modern style is right for your implementation, update and redeploy the application with the new style ID following the guidance on this page.

To understand how this migration will affect your pricing, refer to the notes on this page about tile sizes, as well as our Pricing by products page.

Leaflet implementations

If you are using Leaflet with a classic style (for example, mapbox.streets), update the application to 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.

There is not a modern Mapbox equivalent for some of the Mapbox-maintained classic styles we list on this page. Refer to the Mapbox Styles API and the Mapbox Gallery to find the available modern Mapbox styles.

var map = L.map('map');
 
L.tileLayer('https://api.mapbox.com/styles/v1/{id}/tiles/{z}/{x}/{y}?access_token={accessToken}', {
attribution: '© <a href="https://www.mapbox.com/about/maps/">Mapbox</a> © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a> <strong><a href="https://www.mapbox.com/map-feedback/" target="_blank">Improve this map</a></strong>',
tileSize: 512,
maxZoom: 18,
zoomOffset: -1,
id: 'mapbox/streets-v12',
accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN'
}).addTo(map);

Mapbox.js implementations

Because Mapbox.js is a plugin for Leaflet, the migration pattern is similar. Rather than passing the string ID of a Mapbox template style (for example, 'mapbox.streets'), you will initialize a styleLayer and add this layer to your map. The earliest version of Mapbox.js that uses styleLayer is 2.3.0. If you are using an older version of this library, you will need to upgrade to at least version to 2.3.0 to complete this migration. If possible, we recommend that you upgrade to the most recent version of Mapbox.js.

L.mapbox.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
 
var map = L.mapbox.map('map')
.setView([40, -74.50], 9)
.addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));

Static Tiles API tile size implications

By default, the Static Tiles API serves 512×512 tiles that each cover an area four times as large as those served by the Raster Tiles API, which are 256×256. Some mapping libraries, including Leaflet and Mapbox.js, are built around map tiles that cover a particular geographic area at a given zoom. To support libraries like this that expect smaller tiles, the Static Tiles API can serve both 512×512 and 256×256 tiles, 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. This can have significant cost implications. 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.

• If you are using Mapbox.js, you can use a styleLayer.
• If you are using Leaflet, you can use a zoomOffset option.

Your implementation will vary if you are using a different mapping library.

FAQs

How can I tell if my style is a classic style or a modern Mapbox style?

Classic styles are named with the following convention: your_username.some_string or mapbox.some_string. For example: mapbox.streets, mapbox.light, and mapbox.pirates. 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 as well as classic styles.

In contrast, modern Mapbox styles are identified by style URLs with the following pattern: your_username/some_string or mapbox/some_string. If your application code reference styles like username/custom_style or mapbox/streets, then you're using a modern style.

Which classic styles are being deprecated?

All Mapbox classic styles have been deprecated. The following is a list of the Mapbox-maintained classic styles that cannot be requested by new applications:

• mapbox.streets
• mapbox.light
• mapbox.dark
• mapbox.streets-satellite
• mapbox.outdoors
• mapbox.run-bike-hike
• mapbox.streets-basic
• mapbox.wheatpaste
• mapbox.comic
• mapbox.pencil
• mapbox.pirates
• mapbox.emerald
• mapbox.high-contrast

Applications that make requests to these styles must be updated to reference a modern Mapbox style.

How can I determine if my application is using a classic style?

If you received emails from Mapbox about migrating from classic styles to modern Mapbox styles, but aren't sure where to start making updates, use the following techniques to identify which classic styles are being used in your applications:

1. Review the account's Statistics page.

• Log in to the account.
• Navigate to the Statistics page.
• Select a date range of 30 days or fewer.
• Isolate Tileset IDs additional metric within the Raster Tiles API section. Compare the displayed Tileset IDs requested by All tokens and applications for the selected date range to the list of classic styles.

2. Review the application's source code. In the code file, search for the following. Results matching these patterns might be associated with classic styles:

• Search for the account's username, looking for any references in the format your_username.some_string.
• Search for mapbox., looking for any references in the format mapbox.some_string.

Where can I find the custom classic styles in my account?

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: https://studio.mapbox.com/classic/. Note that Mapbox-designed classic styles you may be using will not appear in this list. To see the full list of classic styles that you are using:

• Log in to the account.
• Navigate to the Statistics page.
• Select a date range of 30 days or fewer.
• Isolate Tileset IDs additional metric within the Raster Tiles API section. Compare the displayed Tileset IDs requested by All tokens and applications for the selected date range to the list of classic styles.

All these styles and projects are deprecated. If you know a style in this list is being referenced by your application, you need to create a new custom style with Mapbox Studio.

Do the APIs return an error when classic styles are requested?

Yes, the APIs return 410: gone when making a direct request in the browser or using curl for requests made by accounts that no longer support classic styles. To fix this error, update the requests to reference a modern Mapbox style. For more information, refer to the Static Tile API documentation.

Is Mapbox.satellite one of the deprecated Mapbox-designed classic styles?

No, Mapbox Satellite is an actively maintained Mapbox raster tileset. It is available through our APIs and SDKs by using the style URL mapbox://styles/mapbox/satellite-v9 or tileset ID mapbox.satellite. All customers can continue requesting this tileset using the Raster Tiles API.

How can I confirm that my migration from classic to modern styles is complete?

It may take several days to visually confirm the impact of your updates on the account's Statistics page, since that service updates on a 24 hour schedule. Review the account's Statistics page one week after the updates have been deployed to chart progress toward the full adoption of modern styles. The end users of your mobile applications must upgrade their version of the app to start using the modern styles referenced in your latest release.

What if I am using the classic styles via a third party plug-in?

We notified the maintainers of third party plugins about the shutdown of Mapbox classic styles, but it is possible they have not migrated their styles yet. If you are using a Mapbox classic style through a third party plugin, we suggest you contact the plugin's maintainer and ask them to update their plugin to use a modern Mapbox style.

If I cannot resolve my issue, what information should I include in my support request?

Do you have questions that are not covered in this FAQ? Contact our support team with Classic style deprecation as the product type selection. include as much of the following information as you can provide:

Accounts and styles

This information helps us identify the resources you need help migrating:

• Account ID (username)
• Account's registered email address
• Style ID

If you don't know any of this account information, we can use an access token to identify the account.

Applications

This information helps us understand which steps in this migration guide you have tried:

• Overview of applications using classic styles or legacy APIs (how many, which technologies, who uses it, and other relevant details).
• Outline of chosen path forward for legacy styles in the applications: Will you be updating the application to a modern, Mapbox GL template style, or recreating a classic style with the modern Mapbox tools?
• Description of the steps you tried, and where you got stuck.

The Mapbox support team needs these details to be able to address your specific use case. Thanks in advance for providing as much information as possible in your support request!

Additional resources

• Leaflet Documentation
• Mapbox.js Documentation
• Mapbox.js & Leaflet Pricing Guide
• Mapbox Studio Manual - Styles