All docsAPIMapsStatic Images

Static Images

The Mapbox Static Images API serves standalone, static map images generated from Mapbox Studio styles. These images can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map, but do not have interactivity or controls.

playground
Static Images API playground

Build a Static Images API request by zooming and panning around an interactive map.

Retrieve a static map from a style

get
/styles/v1/{username}/{style_id}/static/{overlay}/{lon},{lat},{zoom},{bearing},{pitch}|{bbox}|{auto}/{width}x{height}{@2x}
styles:tiles

The position of the map is represented by either the word auto, a bounding box, or by five numbers: longitude, latitude, zoom, bearing, and pitch. The last two numbers, bearing and pitch, are optional. If you only specify bearing and not pitch, pitch will default to 0. If you specify neither, they will both default to 0. If you specify auto or bbox, you should not provide any of these numbers.

  • For styles that contain vector layers, the returned static map will be a PNG.
  • For styles that contain only raster layers, the returned static map will be a JPEG.
Required parametersDescription
usernameThe username of the account to which the style belongs.
style_idThe ID of the style from which to create a static map.
overlayOne or more comma-separated features that can be applied on top of the map at request time. The order of features in an overlay dictates their Z-order on the page. The last item in the list will have the highest Z-order (will overlap the other features in the list), and the first item in the list will have the lowest (will underlap the other features). Format can be a mix of geojson, marker, or path. For more details on each option, see the Overlay options section.
lonLongitude for the center point of the static map; a number between -180 and 180.
latLatitude for the center point of the static map; a number between -85.0511 and 85.0511.
zoomZoom level; a number between 0 and 20. Fractional zoom levels will be rounded to two decimal places.
bboxFour coordinates representing upper longitude, upper latitude, lower longitidue, lower latitude, enclosed in square brackets like [lon(min),lat(min),lon(max),lat(max)]. bbox is used in place of lon,lat,zoom or auto. The zoom level is calculated based on the most detailed zoom level that fits the bounding box within the request's specified width and height. Increasing the request's width and height will return a map at a higher zoom level. See the bbox example requests for how to retrieve a static map using a bounding box.
autoIf auto is used, the viewport will fit the bounds of the overlay. If used, auto replaces lon, lat, zoom, bearing, pitch, and bbox.
widthWidth of the image; a number between 1 and 1280 pixels.
heightHeight of the image; a number between 1 and 1280 pixels.

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

Optional parametersDescription
bearingBearing rotates the map around its center. A number between 0 and 360, interpreted as decimal degrees. 90 rotates the map 90° clockwise, while 180 flips the map. Defaults to 0.
pitchPitch tilts the map, producing a perspective effect. A number between 0 and 60, measured in degrees. Defaults to 0 (looking straight down at the map).
@2xRender the static map at a @2x scale factor for high-density displays.
attributionA boolean value controlling whether there is attribution on the image. Defaults to true. Note: If attribution=false, the watermarked attribution is removed from the image. You still have a legal responsibility to attribute maps that use OpenStreetMap data, which includes most maps from Mapbox. If you specify attribution=false, you are legally required to include proper attribution elsewhere on the webpage or document.
logoA boolean value controlling whether there is a Mapbox logo on the image. Defaults to true.
before_layerA string value for controlling where the overlay is inserted in the style. All overlays will be inserted before the specified layer.
addlayerAn object value that adds a Mapbox style layer to the map's style at render time. Can be combined with before_layer. See Style Parameters for more information.
setfilterAn array value that adheres to Mapbox's expression syntax. Applies a filter to an existing layer in a style. Must be used with layer_id. See Style Parameters for more information.
layer_idA string value that denotes the layer in the style that the filter specified in setfilter is applied to.
paddingA string value that denotes the minimum padding per side of the image. This can only be used with auto or bbox. The value resembles the CSS specification for padding and accepts 1-4 integers without units. For example, padding=5 declares a minimum padding of 5 pixels for all sides, whereas padding=5,8,10,7 declares a minimum of 5 pixels of top padding, 8 pixels of right padding, 10 pixels of bottom padding, and 7 pixels of left padding. Defaults to a value that is 5% of the smallest side of the image, rounded up to the next integer value, up to a maximum of 12 pixels of padding per side.

Example requests

Example requests: Retrieve a static map from a style

# Retrieve a map at -122.4241 longitude, 37.78 latitude,
# zoom 15.25, bearing 0, and pitch 60. The map
# will be 400 pixels wide and 400 pixels high
# and save the output as a PNG image.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-122.4241,37.78,15.25,0,60/400x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-1.png

# Retrieve a map at 0 longitude, 10 latitude, zoom 3,
# and bearing 20. Pitch will default to 0
# and save the output as a PNG image.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/0,10,3,20/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-2.png

# Retrieve a map at 0 longitude, 0 latitude, zoom 2.
# Bearing and pitch default to 0
# and save the output as a PNG image.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-3.png

# Querying a style with raster layers returns a JPEG
# and save the output as a JPEG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/satellite-v9/static/0,0,2/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-4.jpg

Example request: Retrieve a static map using a bounding box

Retrieve a map that fits the bounding box [-77.043686,38.892035,-77.028923,38.904192] and save the output as a PNG image that is 400 pixels wide and 400 pixels high.

$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/[-77.043686,38.892035,-77.028923,38.904192]/400x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-bbox-1.png

Example response: Retrieve a static map using a bounding box

Example request: Retrieve a static map using a bounding box with padding

The bbox parameter can be combined with padding as well. Using the same bounding box from the previous example, this request adds 50 pixels of top padding, 10 pixels of side padding, and 20 pixels of bottom padding.

$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/[-77.043686,38.892035,-77.028923,38.904192]/400x400?padding=50,10,20&access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-bbox-2.png

Example response: Retrieve a static map using a bounding box with padding

Example request: Retrieve a static map image in an HTML file

<!-- Retrieve a map at -87.0186 longitude, 32.4055 latitude, -->
<!-- zoom 14, bearing 0. Pitch will default to 0. -->
<!-- The map will be 500 pixels wide and 300 pixels high. -->
<img src="https://api.mapbox.com/styles/v1/mapbox/light-v10/static/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" alt="Map of the Edmund Pettus Bridge in Selma, Alabama, with a black 'L' marker positioned in the middle of the bridge.">

Response: Retrieve a static map from a style

  • For styles that contain vector layers, the returned static map will be a PNG.
  • For styles that contain only raster layers, the returned static map will be a JPEG.
Endpoint support

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Overlay options

You can use overlay options to add markers, custom images, or other shapes on top of a static map image at the time of request.

For some parameters, the Static images API requires that values be encoded as URI components. You can encode those values using encodeURIComponent() or other encoding tools.

GeoJSON

geojson({geojson})
ArgumentDescription
geojsonThe {geojson} argument must be a valid GeoJSON object encoded as a URI component. simplestyle-spec styles for GeoJSON features will be respected and rendered. Note that # characters must be replaced in the URL with %23 (for example, "fill":"#FF0000" would be "fill":"%23FF0000").
API request URL length limit

Using a large GeoJSON object as an argument to the overlay parameter will lengthen your request URL and this may result in hitting the 8,192 byte URL length limit. Options for shortening the resulting URL length include:

  • Simplifying your GeoJSON using a third party library, such as simplify-geojson, before passing it as an argument.
  • Limiting the precision of coordinates in the GeoJSON to five or six decimal places.
  • Adding a large GeoJSON polygon or other object to a custom style in Mapbox Studio, then passing the style ID to the Static Images API style_id parameter instead of passing the GeoJSON to the overlay parameter. See Part 1 of our Make a choropleth map tutorial for guidance.

Example request: Retrieve a static map with a GeoJSON Point overlay

# Retrieve a static map with a GeoJSON overlay
# and save the output as a PNG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/geojson(%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-73.99%2C40.7%5D%7D)/-73.99,40.70,12/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-GeoJSON.png

Example response: Retrieve a static map with a GeoJSON Point overlay

Example request: Retrieve a static map with a GeoJSON FeatureCollection overlay

# Retrieve a 500×300px static map image with a GeoJSON
# overlay including three colored markers with
# Maki icons and save the output as a PNG image.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/geojson(%7B%22type%22%3A%22FeatureCollection%22%2C%22features%22%3A%5B%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23462eff%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22bus%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25993633270264,37.80988566878777%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23e99401%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22park%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25916385650635,37.80629162635318%5D%7D%7D%2C%7B%22type%22%3A%22Feature%22%2C%22properties%22%3A%7B%22marker-color%22%3A%22%23d505ff%22%2C%22marker-size%22%3A%22medium%22%2C%22marker-symbol%22%3A%22music%22%7D%2C%22geometry%22%3A%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-122.25650310516359,37.8063933469406%5D%7D%7D%5D%7D)/-122.256654,37.804077,13/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-GeoJSON3.png

Example response: Retrieve a static map with a GeoJSON FeatureCollection overlay

Marker

{name}-{label}+{color}({lon},{lat})
ArgumentDescription
nameMarker shape and size. Options are pin-s and pin-l.
label
(optional)
Marker symbol. Options are a lowercase alphanumeric label a through z, 0 through 99, or a valid Maki icon. If a letter is requested, it will be rendered in uppercase only.
color
(optional)
A 3- or 6-digit hexadecimal color code.
lon, latThe location at which to center the marker. When using an asymmetric marker, make sure that the tip of the pin is at the center of the image.

Example request: Retrieve a static map with a marker overlay

# Retrieve a static map with a marker overlay
# and save the output as a PNG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v10/static/pin-s-l+000(-87.0186,32.4055)/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker.png

Example response: Retrieve a static map with a marker overlay

Example request: Retrieve a static map with a Maki icon overlay

# Retrieve a static map with a large marker overlay
# Marker has a Maki icon label and background color `#f74e4e`
# Output is saved as a PNG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/dark-v10/static/pin-l-embassy+f74e4e(-74.0021,40.7338)/-74.0021,40.7338,16/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker-pin-maki-icon.png

Example response: Retrieve a static map with a Maki icon overlay

Example request: Retrieve a static map with a marker overlay in an HTML file

<!-- Retrieve a static map with marker overlay that is -->
<!-- a small pin with a letter 'L' label and black color -->
<img src="https://api.mapbox.com/styles/v1/mapbox/light-v10/static/pin-s-l+000(-87.0186,32.4055)/-87.0186,32.4055,14/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" alt="Static map image of Edmund Pettus Bridge in Selma, Alabama, using the Dark map style, with a black marker with the letter 'L' positioned in the middle of the bridge.">

Custom marker

url-{url}({lon},{lat})
ArgumentDescription
urlA percent-encoded URL for the image. Type can be PNG or JPG.
lon, latThe location at which to center the marker. When creating an asymmetric marker like a pin, make sure that the tip of the pin is at the center of the image.

Custom marker overlays are not automatically scaled or modified if used simultaneously with @2x, so you must ensure that the icon used as a custom marker is the appropriate size prior to making the request.

Custom markers are cached according to the Expires and Cache-Control headers. Set at least one of these headers to a proper value to prevent repeated requests for the custom marker image.

The type value for custom markers must be set using the Content-Type key in the response header of the marker URL request. Acceptable values are image/png and image/jpeg.

Example request: Retrieve a static map with a custom marker overlay

# Retrieve a map with a custom marker overlay
# and save the output as a PNG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v10/static/url-https%3A%2F%2Fdocs.mapbox.com%2Fapi%2Fimg%2Fcustom-marker.png(-76.9,38.9)/-76.9,38.9,15/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-marker-custom.png

Example response: Retrieve a static map with a custom marker overlay

Path

path-{strokeWidth}+{strokeColor}-{strokeOpacity}+{fillColor}-{fillOpacity}({polyline})

Encoded polylines with a precision of 5 decimal places can be used with the Static API via the path parameter.

ArgumentDescription
strokeWidth
(optional)
A positive number for the line stroke width
strokeColor
(optional)
A 3- or 6-digit hexadecimal color code for the line stroke
strokeOpacity
(optional)
A number between 0 (transparent) and 1 (opaque) for line stroke opacity
fillColor
(optional)
A 3- or 6-digit hexadecimal color code for the fill
fillOpacity
(optional)
A number between 0 (transparent) and 1 (opaque) for fill opacity
polylineA valid encoded polyline encoded as a URI component

Example request: Retrieve a static map with a path overlay

# Retrieve a map with two points and a polyline overlay,
# with its center point automatically determined with `auto`
# and save the output as a PNG image
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/pin-s-a+9ed4bd(-122.46589,37.77343),pin-s-b+000(-122.42816,37.75965),path-5+f44-0.5(%7DrpeFxbnjVsFwdAvr@cHgFor@jEmAlFmEMwM_FuItCkOi@wc@bg@wBSgM)/auto/500x300?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-overlay-polyline.png

Example response: Retrieve a static map with a path overlay

Style parameters

Style parameters allow you to change the requested map style at render time.

Style parameter requests must specify a lon, lat, and zoom in the request. Using the auto extent will result in an error if the request does not also include an overlay.

Add a style layer

You can add a style layer to your static image request by using the addlayer query parameter. The addlayer query parameter accepts a Mapbox style layer to add a new layer to the rendered map. The layer you add must be from a Mapbox source or an existing source in your account.

To use the addlayer parameter, format your request like:

# Add a road overlay layer from the existing composite source
# The hex code for "line-color" is URI encoded
https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-122,37,9/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&addlayer={"id":"road-overlay","type":"line","source":"composite","source-layer":"road","filter":["==",["get","class"],"motorway"],"paint":{"line-color":"%23ff0000","line-width":5}}

To specify the z-index of the new layer by using the before_layer query parameter. For example, the following request will place the new layer road-overlay before road-label:

# Add a road overlay layer from the existing composite source
# The hex code for "line-color" is URI encoded
https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-122,37,9/600x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&addlayer={"id":"road-overlay","type":"line","source":"composite","source-layer":"road","filter":["==",["get","class"],"motorway"],"paint":{"line-color":"%23ff0000","line-width":5}}&before_layer=road-label
Overlays and before_layer priority

When addlayer is used in conjunction with an overlay and a before_layer is specified, the layer defined in the addlayer parameter will always be inserted beneath the indicated layer and the overlay will be added on top of the map.

To add a style layer from a source that is not already part of the style, you must specify source.url and source.type in the new style layer, like:

"source": {
  "type": "vector",
  "url": "mapbox://{username}.{tileset}"
}

source.url must be a mapbox:// tileset URL, and must be accessible to the access token used in the request. source.type must be either raster or vector. If you want to add an image or geojson as a new layer, you should use their respective overlay options.

Example request: Retrieve a static map with an added style layer

# Add a layer called "better-boundary" using data from the source layer
# `admin`, filtered to include only state boundaries, matching the U.S.
# worldview, and style the resulting lines red (#DB6936) with a dashed line.
# Special characters in the request are encoded.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/light-v10/static/-96.561208,38.790325,3/800x400@2x?addlayer={%22id%22:%22better-boundary%22,%22type%22:%22line%22,%22source%22:%22composite%22,%22source-layer%22:%22admin%22,%22filter%22:[%22all%22,[%22==%22,[%22get%22,%22admin_level%22],1],[%22==%22,[%22get%22,%22maritime%22],%22false%22],[%22match%22,[%22get%22,%22worldview%22],[%22all%22,%22US%22],true,false],[%22==%22,[%22get%22,%22iso_3166_1%22],%22US%22]],%22layout%22:{%22line-join%22:%22bevel%22},%22paint%22:{%22line-color%22:%22%23DB6936%22,%22line-width%22:1.5,%22line-dasharray%22:[1.5,1]}}&before_layer=road-label&access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output example-mapbox-static-style-parameters-addlayer.png

Example response: Retrieve a static map with an added style layer

Filter existing features

To apply a filter expression to an existing style layer, you can use the setfilter and layer_id query parameters. setfilter accepts a valid filter expression, while layer_id specifies the layer in the style to add the filter to.

For example, to filter out country labels to only display "Canada", you could do the following:

https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-91,60,2/800x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&setfilter=["==","name_en","Canada"]&layer_id=country-label

If you are using setfilter, you must specify a layer with layer_id. The layer_id must be a valid layer in the style.

Example request: Retrieve a static map with filtered layer

# Filter data in the `country-label` layer to
# display only data matching the string "Canada".
# Special characters in the request are encoded.
$ curl -g "https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-96.8,47.3,1.8/800x400?access_token=YOUR_MAPBOX_ACCESS_TOKEN&setfilter=[%22==%22,%22name_en%22,%22Canada%22]&layer_id=country-label" --output example-mapbox-static-style-parameters-setfilter.png

Example response: Retrieve a static map with filtered layer

Static Images 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. See 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-20.422The zoom level specified in the query is larger than 20 or contains non-numeric characters.
Pitch must be between 0-60.422The pitch specified in the query is larger than 60 or contains non-numeric characters.
{Width}/{Height} must be between 1-1280.422The width or the height specified in the query is larger than 1280 or contains non-numeric characters.
Auto extent cannot be used with style parameters and no overlay422/auto/ is used for the extent in a request with style parameters that does not include an overlay. You should instead specify a longitude, latitude, and zoom for the request.
Auto extent cannot be determined when GeoJSON has no features422/auto/ is used for the extent in a request with a GeoJSON overlay that has no features. For example, geojson({"type":"FeatureCollection","features":[]}). You should instead specify a longitude, latitude, and zoom for the request.
The auto parameter cannot be used with additional location parameters, bearing, or pitch.422Additional location parameters (lon, lat, zoom), bearing, and pitch cannot be used with the auto parameter.
The bounding box parameter cannot be used with additional location parameters, bearing, or pitch.422Additional location parameters (lon, lat, zoom), bearing, and pitch cannot be used with the bbox parameter.
The GeoJSON argument has an unknown or unsupported geometry type422The GeoJSON geometry type in the overlay is not a supported geometry type.
You can only use {addlayer}/{setfilter} once per request422Only one style parameter can be used in a single request.
addlayer and setfilter cannot be used in the same request422Only one style parameter can be used in a single request. If you want to apply a filter to a new style layer, you should add a filter to the style layer object in the addlayer request.
The new layer's source reference key does not match any source keys in the requested style. Please specify url and type in the source for the new layer.422The source specified in the addlayer request does not match the requested style. You should reformat the new layer source so that it's an object with a type and url (eg source: { url: 'mapbox://mapbox.mapbox-streets-v8', type: 'vector'}).
The new layer source url must be a properly formatted mapbox:// url (eg. mapbox://mapbox.mapbox-streets-v7)422The new layer's source url is not formatted correctly.
Layer is missing required attributes (id, type, source)422The layer is missing an id, type, or source value. The new layer should follow Mapbox style layer syntax.
New layer sources must contain a source type and url422The new layer source is missing the source type or url.
New layers must be added with unique ids422The newly added layer has the same name as an existing layer in the style. You should rename the layer id to something else.
New layer type must be one of the following types: background, fill, line, symbol, circle, fill-extrusion, heatmap, hillshade, raster422The new layer type must be a valid Mapbox GL JS layer type
Must include layer_id in setfilter request422setfilter must be used with layer_id in order to know what layer to apply the filter to.
layer_id must be an existing layer in the requested style422You can only apply the setfilter param to an existing layer in the style.
Invalid filter syntax422The expression passed to setfilter is not a valid expression.
Invalid layer passed to addlayer. Unable to parse JSON.422The JSON passed to addlayer is invalid.
Padding must be 1-4 numbers, comma-delimited.422Padding must be 1-4 numbers (no units, since pixels are implied) that are comma-delimited, resembling the CSS specification for padding, like padding=5 or padding=5,8,10,7.
The padding cannot exceed the height or width of the requested image.422The sum of the top and bottom padding cannot exceed the image height, and the sum of the left and right padding cannot exceed the image width.
Padding cannot be used without the auto parameter or without a provided bounding box.422Padding can only be used with the auto parameter or with location specified by a bbox. Without the auto parameter or the bbox parameter, requests expect lon, lat, and zoom, and these values would change if asking for padding with a fixed image size.
Invalid bbox: *422The provided bbox is invalid. Make sure the bbox contains 4 valid coordinates enclosed in square brackets and are ordered like [lon(min),lat(min),lon(max),lat(max)].
Overlay bounds are out of range.422The overlay coordinates are out of map range. Make sure the overlay coordinates are within range, meaning longitude between -180 and 180 and latitude between -85.0511 and 85.0511.

Static Images API restrictions and limits

  • The default rate limit for the Mapbox Static Images API endpoint is 1,200 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 Images 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 Images 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 Images API pricing

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

Usage of the Static Images API is measured in API requests. 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.