The Mapbox Static Tiles API serves raster tiles generated from Mapbox Studio styles. Raster tiles can be used in traditional web mapping libraries like Mapbox.js, Leaflet, OpenLayers, and others to create interactive slippy maps. The returned raster tile will be a JPEG, and will be 512 pixels by 512 pixels by default.
For information on how the Static Tiles API is billed, visit the Pricing by product guide.
Retrieve 512x512 pixel or 256x256 pixel raster tiles from a Mapbox Studio style. The returned raster tile will be a JPEG.
|The username of the account to which the style belongs.|
|The ID of the style from which to return a raster tile.|
|The tile coordinates as described in the Slippy Map Tilenames specification. They specify the tile's zoom level |
You can further refine the results from this endpoint with the following optional parameters:
|Default is 512x512 pixels. (512x512 image tiles are offset by one zoom level compared to 256x256 tiles from Mapbox Studio Classic styles. For example, 512x512 tiles at zoom level 4 are equivalent to Mapbox Studio Classic styles tiles at zoom level 5.) 256x256 tiles from the endpoint are one quarter of the size of 512x512 tiles. Therefore, they require 4 times as many API requests and accumulate 4 times as many map views to render the same area.|
|Render the raster tile at a |
# Returns a default 512x512 pixel tile $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/1/1/0?access_token=YOUR_MAPBOX_ACCESS_TOKEN" # Returns a 256x256 pixel tile $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/256/1/1/0?access_token=YOUR_MAPBOX_ACCESS_TOKEN" # Returns a 1024x1024 pixel tile $ curl "https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/512/1/1/0@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
The returned 512x512 pixel or 256x256 pixel raster tile will be a JPEG.
|Response body ||HTTP status code||Description|
|Check the access token you used in the query.|
|Check the style ID used in the query.|
|Classic styles are no longer supported for your account. See this guide for migrating your implementation to the modern Static Tiles API, and this Deprecating Studio Classic styles blog post for additional deprecation details.|
|The zoom level specified in the query is larger than 20 or contains non-numeric characters.|
- The default rate limit for the Mapbox Static Tiles API endpoint is 5,000 requests per minute. If you require a higher rate limit, contact us.
- If you exceed the rate limit, you will receive an
HTTP 429 Too Many Requestsresponse. For information on rate limit headers, see the Rate limit headers section.
- The caching behavior of the Static Tiles API is different than that of other Mapbox services. The longest amount of time you could potentially wait until a change is propagated to a static map is 12 hours. In the responses for requests made to the Static Tiles API endpoint, the following caching headers are set:
max-age=43200, s-maxage=604800if the style uses
max-age=43200, s-maxage=43200otherwise. These
Cache-Controlheaders are meant to show how long a source is considered valid for either the client or any request handled by our CDN. So, it is expected caching behavior that your static map might take up to 12 hours to update after making changes. Note that styles or tilesets which set custom cache headers will override these default header values.