Maps APIs Caching | Help

Caching

Caching information specific to each of Mapbox's Maps APIs is in the "Restrictions and limits" section near the end of each individual Maps API page. But some tips on working with caching are common across Maps APIs.

Glossary

TTL (Time To Live): The lifetime of an object before the CDN replaces it with a new version.
CDN (Content Delivery Network): Globally distributed entry point for all HTTP requests at api.mapbox.com. Our CDN caches responses for defined time intervals to improve performance.
Cache-Control: The standardized HTTP header for directing cache instructions for requests and responses. Most Maps APIs set both a max-age (or device cache TTL) cache-control header and a s-maxage (or CDN cache TTL) cache-control header.

How long does it take for changes to a style or tileset to be reflected in my map?

Cache times for styles and tilesets depend on whether you're making direct API requests or using a Mapbox SDK. With Mapbox SDKs, you have the option of invalidating the device cache.

Tileset changes

To find the cache defaults for an API where a tileset is used, you can look at the "Restrictions and limits" section near the end of the individual API page. For example, there will be at least a 5-minute delay to show newly created tiles for an existing tileset used in the Vector Tiles API or Mapbox GL JS. The device TTL for vector tiles is 12 hours — see below for details on breaking the device cache.

If an implementation relies on our Static APIs, data updates to cached tiles won't be visible for at least 12 hours due to the CDN cache default. You cannot break the CDN cache.

Style changes

After you have published changes to a style, there will be at least a 15-minute delay to see the update reflected in a map. If the map style used in an application was rendered on a device before that style was updated, then the limiting factor may be the vector tile TTL, since the default device TTL is 12 hours — see below for details on breaking the device cache.

Any style changes propagating downstream to the Static API won't be visible for at least 12 hours due to the CDN cache default. You cannot break the CDN cache.

How can I break the device cache?

To invalidate the device cache with Mapbox SDKs, you can use the relevant methods linked here: Mapbox Maps SDK for Android, Mapbox Maps SDK for iOS, or Mapbox GL JS.
On the web, you can clear your browser cache via developer tools or browse in incognito mode.