All docsAPIMapsRaster Tiles

Raster Tiles

The Mapbox Raster Tiles API serves raster tiles generated from satellite imagery tilesets and tilesets generated from raster data uploaded to

For information on how the Raster Tiles API is billed, visit the Pricing by product guide.

Retrieve raster tiles

Required parametersDescription
tileset_idUnique identifier for the raster tileset in the format To composite multiple tilesets, use a comma-separated list of up to 15 tileset IDs.
zoomSpecifies the tile's zoom level, as described in the Slippy Map Tilenames specification.
{x}/{y}Specifies the tile's column {x} and row {y}, as described in the Slippy Map Tilenames specification.
formatSpecifies the format of the returned tiles:
.pngTrue color PNG
.png3232 color indexed PNG
.png6464 color indexed PNG
.png128128 color indexed PNG
.png256256 color indexed PNG
.jpg7070% quality JPG
.jpg8080% quality JPG
.jpg9090% quality JPG
The format of any image request can be replaced by any of these formats to adjust image quality for different bandwidth requirements. Higher-compression formats like jpg70 or png32 can be useful to favor performance over image quality.

Note: Tiles that include mapbox.satellite are always delivered as JPEGs, even if the URL specifies PNG. The PNG format can't efficiently encode photographic images like those used by mapbox.satellite.
Optional parametersDescription
@2xRequest a higher DPI version of the image.

Example request: Retrieve raster tiles

# Retrieve a 2x tile; this 512x512 tile is appropriate for high-density displays

$ curl ""

Response: Retrieve raster tiles

The response is a raster image tile in the specified format. For performance, image tiles are delivered with a max-age header value set 12 hours in the future.

Raster Tiles API errors

Response body messageHTTP status codeDescription
Not Authorized - No Token401No token was used in the query.
Not Authorized - Invalid Token401Check the access token you used in the query.
Tileset {tileset name} does not exist404Check the name of the tileset you used in the query.
Tile not found404Check the column and row of the tile requested in the query.
Zoom level must be between 0-30.422The zoom level specified in the query is larger than 30 or contains non-numeric characters.
Invalid quality value {value} for raster format {jpg/png}422The format specified in the query must be one of the formats listed in the Retrieve raster tiles section of this documentation.

Raster Tiles API restrictions and limits

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