All docsAPIMapsStatic Tiles

Static Tiles

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 raster tiles from styles

get
/styles/v1/{username}/{style_id}/tiles/{tilesize}/{z}/{x}/{y}{@2x}

Retrieve 512x512 pixel or 256x256 pixel raster tiles from a Mapbox Studio style. The returned raster tile will be a JPEG.

Libraries like Mapbox.js and Leaflet.js use this endpoint to render raster tiles from a Mapbox Studio style with L.mapbox.styleLayer and L.tileLayer.

Required parametersDescription
usernameThe username of the account to which the style belongs.
style_idThe ID of the style from which to return a raster tile.
{z}/{x}/{y}The tile coordinates as described in the Slippy Map Tilenames specification. They specify the tile's zoom level {z}, column {x}, and row {y}.

You can further refine the results from this endpoint with the following optional parameters:

Optional parametersDescription
tilesizeDefault 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.
@2xRender the raster tile at a @2x scale factor, so tiles are scaled to 1024x1024 pixels.

Example request: Retrieve raster tiles from styles

# 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"

Response: Retrieve raster tiles from styles

The returned 512x512 pixel or 256x256 pixel raster tile will be a JPEG.

Static Tiles API errors

Response body messageHTTP status codeDescription
Not Authorized - Invalid Token401Check the access token you used in the query.
Style not found404Check the style ID used in the query.
Classic styles are no longer supported410Classic 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.
Invalid style source422The sources key within the style your request references contains an invalid value.
Zoom level must be between 0-20.422The zoom level specified in the query is larger than 20 or contains non-numeric characters.

Static Tiles API restrictions and limits

  • 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 Requests response. 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=604800 if the style uses mapbox.satellite, and max-age=43200, s-maxage=43200 otherwise. These Cache-Control headers 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.