Static Images API

And still achieve the same visual result.

If you are reusing a custom marker for multiple points, you can include the custom URL as the "marker-url" property in your GeoJSON overlay.

5. Reduce coordinate precision. In web applications it is common to use latitude and longitude values with high amounts of decimal precision. But it is rarely necessary to use more than six decimals of precision for Static Images API requests. Rounding any coordinate values in your request to the sixth decimal will help trim down long URLs.

6. Remove feature properties, if relying on defaults. For overlays, the Static Images API will set a default value for the feature if no value is provided for certain simplestyle properties. If you are already using the default value or are comfortable relying on the default values, removing the explicit declaration of these style properties in your overlays can help reduce URL length:

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-v12/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 ​

View static image chevron-right

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-v12/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 ​

View static image chevron-right

Marker ​

{name}-{label}+{color}({lon},{lat})

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-v11/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 ​

View static image chevron-right

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-v11/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 ​

View static image chevron-right

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-v11/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})

Custom marker overlays are not automatically scaled or modified if used simultaneously with @2x , so you must make sure that the image used as a custom marker is the appropriate size before making the request. The height and width of images used as custom marker overlays cannot exceed 1,024 pixels.

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.

You must declare the type value for custom markers 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-v11/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 ​

View static image chevron-right

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.

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-v12/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 ​

View static image chevron-right

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-v12/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-v12/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}"
}

clipboard

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-v11/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

clipboard

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

View static image chevron-right

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-v12/static/-91,60,2/800x600?access_token=YOUR_MAPBOX_ACCESS_TOKEN&setfilter=["==","name_en","Canada"]&layer_id=country-label

clipboard

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-v12/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

clipboard

Example response: Retrieve a static map with filtered layer ​

View static image chevron-right

Static Images API errors ​

Response body message	HTTP status code	Description
Not Authorized - Invalid Token	401	Check the access token you used in the query.
Forbidden	403	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 403 error. For more information, see our Token management guide .
Style not found	404	Check the style ID used in the query.
Classic styles are no longer supported	410	Classic 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 sources	400	The style the request uses contains a source reference that incorrectly composites sources of two different types.
Invalid style source	422	The sources key within the style your request references contains an invalid value.
Zoom level must be between 0-22.	422	The zoom level specified in the query is larger than 22 or contains non-numeric characters.
Pitch must be between 0-60.	422	The pitch specified in the query is larger than 60 or contains non-numeric characters.
{Width}/{Height} must be between 1-1280.	422	The 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 overlay	422	/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 features	422	/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.	422	Additional 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.	422	Additional location parameters ( lon , lat , zoom ), bearing, and pitch cannot be used with the bbox parameter.
The GeoJSON argument has an unknown or unsupported geometry type	422	The GeoJSON geometry type in the overlay is not a supported geometry type .
You can only use {addlayer}/{setfilter} once per request	422	Only one style parameter can be used in a single request.
addlayer and setfilter cannot be used in the same request	422	Only 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. Specify url and type in the source for the new layer.	422	The 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 (for example source: { url: 'mapbox://mapbox.mapbox-streets-v8', type: 'vector'} ).
The new layer source url must be a properly formatted mapbox:// url (for example mapbox://mapbox.mapbox-streets-v7)	422	The new layer's source URL is not formatted correctly.
Layer is missing required attributes (id, type, source)	422	The 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 url	422	The new layer source is missing the source type or url .
New layers must be added with unique ids	422	The 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, raster	422	The new layer type must be a valid Mapbox GL JS layer type
Must include layer_id in setfilter request	422	setfilter must be used with layer_id to know what layer to apply the filter to.
layer_id must be an existing layer in the requested style	422	You can only apply the setfilter parameter to an existing layer in the style.
Invalid filter syntax	422	The expression passed to setfilter is not a valid expression .
Invalid layer passed to addlayer. Unable to parse JSON.	422	The JSON passed to addlayer is invalid.
Padding must be 1-4 numbers, comma-delimited.	422	Padding 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.	422	The 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.	422	Padding 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: *	422	The 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.	422	The 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 .
Height and width must not exceed 1024px	422	The width and height of an image used as a custom marker overlay must be smaller than 1,024 pixels.

Static Images API restrictions and limits ​

The default rate limit for the Mapbox Static Images API endpoint is 1,250 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. The Static Images API endpoint sets the following caching headers in the response: