Troubleshooting

Migrating to the modern Static Tiles API

Mapbox classic style deprecation

As of June 1, 2020, Mapbox classic styles are no longer supported and cannot be requested by new applications.

If your application is still using a custom classic style created with Mapbox Studio Classic, we recommend updating the application to use a modern Mapbox style and the modern Mapbox Static Tiles API.

To recreate your 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.

Play
video
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.

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-v11',
accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN'
}).addTo(map);
Warning

By default, the modern Static Tiles API returns a 512x512 map tile, instead of the 256x256 that Mapbox classic styles returned. If you do not include the tileSize: 512 and zoomOffset: -1 options, your map will still 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 a 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 = L.mapbox.map('map')
.setView([40, -74.50], 9)
.addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
Implications of tile size when using the Static Tiles API

Some mapping libraries, such as Leaflet and Mapbox.js, 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.

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 will be deprecated. The following is a list of the Mapbox-maintained classic styles that are not receiving data updates and cannot be requested by new applications after June 1, 2020:

  • 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 should be updated to reference a modern Mapbox style.

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

If you are receiving 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.
  1. 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.
Find the source code on a webpage

If you don't have access to the source code, but can access a live web map, you can use your browser's developer tools to dig into the map's 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).

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 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.

Will the APIs return an error when classic styles are no longer supported?

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 Mapbox-designed classic styles being deprecated?

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.

If I have updated from classic to modern styles, how can I confirm my migration 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. We recommend reviewing 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 will need to upgrade their version of the app to start using the modern styles referenced in your latest release.

Note

If the application code includes a style URL, which may be formatted as your_username/some_string or mapbox/some_string, then the application is using a modern style and there are no further actions required.

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!

Was this page helpful?