Raster Tiles API
The Mapbox Raster Tiles API serves raster tiles generated from satellite imagery tilesets and tilesets generated from raster data uploaded to Mapbox.com.
Retrieve raster tiles
|string||Unique identifier for the raster tileset in the format |
|integer||Specifies the tile's zoom level, as described in the Slippy Map Tilenames specification.|
|integer||Specifies the tile's column |
|string||Specifies the format of the returned tiles: |
Note: Tiles that include
Note: Some tilesets may display a black background in older browser versions but not in newer browser versions. This is because many modern browsers support the WebP image format. For more information see Troubleshoot raster image with black background.
|string||Request 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 "https://email@example.com?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
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 ||HTTP status code||Description|
|No token was used in the query.|
|Check the access token you used in the query.|
|There 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
|Check the name of the tileset you used in the query.|
|Check the column and row of the tile requested in the query.|
|The zoom level specified in the query is larger than 30 or contains non-numeric characters.|
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 Requestsresponse. For information on rate limit headers, see the Rate limit headers section.
- Responses from the Raster Tiles API set default Cache-Control headers to
max-age=43200,s-maxage=300, or a device cache TTL of 12 hours and a CDN cache TTL of 5 minutes. New tileset data is cached for up to a further 5 minutes on the backend as well.
- If you composite multiple tileset IDs, the API request will have the cache time of the tileset with the highest
- For general information on caching, please see the Maps APIs caching troubleshooting guide.
Raster Tiles API pricing
- Billed by requests
- See rates and discounts per tile requests in the pricing page's Maps section
Usage of the Raster Tiles API is measured in tile requests. Details about the number of tile 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.