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 Static Tiles API is well-suited for maps with limited interactivity or use on devices that do not support WebGL.

Retrieve raster tiles from styles

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

Retrieve raster tiles from a Mapbox Studio style.

  • The returned raster tile will be 512 pixels by 512 pixels by default.
  • If the queried tileset contains raster layers, the returned tile will be a JPEG.
  • If the queried tileset contains only vector layers, the returned tile will be a PNG.

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 parametersTypeDescription
usernamestringThe username of the account to which the style belongs.
style_idstringThe ID of the style from which to return a raster tile.
{z}/{x}/{y}integerThe 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 parametersTypeDescription
tilesizeintegerThe size in pixels of the returned tile, either 512 or 256. The default is 512×512 pixels. Requesting 256×256 tiles from the endpoint can have significant cost implications because they are one quarter of the size of 512×512 tiles. Therefore, 4 times as many API requests must be made to render the same area. Review the pricing guide for details.
@2xstringRender the raster tile at a @2x scale factor, so tiles are scaled to 1024×1024 pixels.
Zoom level and tile size

Note that 512×512 image tiles are offset by one zoom level compared to 256×256 tiles. For example, 512×512 tiles at zoom level 4 are equivalent to 256×256 tiles at zoom level 5.

Example request: Retrieve raster tiles from styles

# Returns a default 512×512 pixel tile as a JPEG
$ curl "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/tiles/1/1/0?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Returns a 1024×1024 pixel tile as a JPEG
$ curl "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/tiles/512/1/1/0@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Response: Retrieve raster tiles from styles

  • The returned raster tile will be 512 pixels by 512 pixels unless you specify otherwise by using the optional tilesize or @2x parameters.
  • If the queried tileset contains raster layers, the returned tile will be a JPEG.
  • If the queried tileset contains only vector layers, the returned tile will be a PNG.

Static Tiles API errors

Response body messageHTTP status codeDescription
Not Authorized - Invalid Token401Check the access token you used in the query.
Forbidden403There may be an issue with your account. Check your Account page for more details.

In some cases, using an access tokens with URL restrictions can also result in a 403 error. For more information, see our Token management guide.
Style not found404Check the style ID used in the query.
Classic styles are no longer supported410Classic styles are no longer supported. 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.
Style may not composite raster sources with vector sources400The style the request uses contains a source reference that incorrectly composites sources of two different types.
Invalid style source422The sources key within the style your request references contains an invalid value.
Zoom level must be between 0-22.422The zoom level specified in the query is larger than 22 or contains non-numeric characters.

Static Tiles API restrictions and limits

  • The default rate limit for the Mapbox Static Tiles API endpoint is 6,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.

Static Tiles API pricing

  • Billed by API requests
  • See rates and discounts per Static Tiles API request in the pricing page's Maps section

The Static Tiles API is measured in API requests. It can be used in conjunction with a raster tile client such as Mapbox.js or Leaflet, a third-party tool such as ArcGIS or Carto, or a hybrid framework. Note that these tiling clients are not actively maintained by Mapbox. Details about the number of requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.

Manage Static Tiles API costs

The Static Tiles API returns 512×512 pixel map tiles by default. While it is possible to use the optional tilesize parameter to request 256x256 pixel tiles, those tiles are one quarter the size of 512x512 tiles and require 4 times as many billable API requests to render a map covering the same area. We recommend that you avoid specifying a tileSize of 256 pixels to prevent unnecessarily high request volume and associated costs.

Some mapping libraries, including Leaflet and Mapbox.js, expect 256x256 pixel tiles but support using a zoom level offset to accurately render 512x512 tiles when specified. Your implementation will vary if you are using a different mapping library.

You can also request 256×256 pixel raster tiles directly with these libraries and the Raster Tiles API by referencing a tileset ID like mapbox.satellite in your implementation. Consider setting maxBounds and maxZoom in the tiling client to limit the number of tiles end users can load. For highly interactive applications, we recommend transitioning to Mapbox GL JS, which is billed by map loads instead of API requests. For additional options, review the guide to managing web map costs.