Static Images API | API Docs (original) (raw)

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.

Retrieve a static map from a style​

get

https://api.mapbox.com

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

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.

Required parameters Type Description
username string The username of the account to which the style belongs.
style_id string The ID of the style from which to create a static map.
overlay string One 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 rest beneath the other features). Format can be a mix of geojson, marker, or path. For more details on each option, see the Overlay options section.
lon number Longitude for the center point of the static map; a number between -180 and 180.
lat number Latitude for the center point of the static map; a number between -85.0511 and 85.0511.
zoom number Zoom level; a number between 0 and 22. Fractional zoom levels will be rounded to two decimal places.
bbox array Four coordinates representing upper longitude, upper latitude, lower longitude, 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 request for how to retrieve a static map using a bounding box.
auto string If auto is used, the viewport will fit the bounds of the overlay. If used, auto replaces lon, lat, zoom, bearing, pitch, and bbox. If auto is used without a specified padding value, padding will automatically be applied with 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.
width number Width of the image; a number between 1 and 1280 pixels.
height number Height 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 parameters Type Description
bearing number Bearing 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.
pitch number Pitch 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).
@2x string Render the static map at a @2x scale factor for high-density displays.
attribution boolean Controls 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.
logo boolean Controls whether there is a Mapbox logo on the image. Defaults to true.
before_layer string Controls where the overlay is inserted in the style. All overlays will be inserted before the specified layer.
addlayer object 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.
setfilter array Applies a filter to an existing layer in a style using Mapbox's expression syntax. Must be used with layer_id. See Style Parameters for more information.
layer_id string Denotes the layer in the style that the filter specified in setfilter is applied to.
padding string 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, where as 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. If auto is used but no value is specified in padding, the default padding will be used (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​

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.

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.

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

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

Response: Retrieve a static map from a style​

Supported libraries: Retrieve a static map from a style​

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​

Argument Type Description
geojson object The {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").

Troubleshooting: Shorten Static Images API requests​

The Static Images API only accepts requests that are 8,192 or fewer characters long. Using a large GeoJSON object as an argument to the overlay parameter will lengthen your request URL. If you find yourself brushing up against this limit, there are a several optimizations that can be used to reduce the length of your Static Images API requests:

1. Use a third-party tool for simplification. You can simplify your GeoJSON using a third party library, such as simplify-geojson, before passing it as an argument.

2. Create a custom style in Studio. Add 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.

3. Remove redundant coordinates in encoded path overlays. On web mercator maps, straight line features require only two coordinates to be rendered correctly. If your request includes path overlays that were encoded with a large amount of points along a straight line, you can reduce the length of your encoded path by removing intermediary coordinates. For example, the line [[0,52], [0,51], [0,50],[0,49]] can be simplified to [[0,52], [0,49]] and still achieve the same visual result.

4. Use GeoJSON for multiple marker overlays. If your request includes several marker overlays that all use the same icon, you can remove the redundancy of specifying each pin-* or url-* overlay by using a GeoJSON overlay that leverages a MultiPoint feature and the simplestyle-spec GeoJSON styling convention instead.

For example, if you have the following path overlay:

You can instead add a GeoJSON overlay with the following data:

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:

Property Default value
marker-color #7e7e7e
stroke #555555
stroke-width 2
stroke-opacity 1.0
fill #555555
fill-opacity 0.6
marker-size medium

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

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

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

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

Marker​

{name}-{label}+{color}({lon},{lat})
Argument Type Description
name string Marker shape and size. Options are pin-s and pin-l.
label string 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 string Optional. A 3- or 6-digit hexadecimal color code.
lon, lat number The 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​

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

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

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​

Custom marker​

Argument Type Description
url string A percent-encoded URL for the image. Type can be PNG or JPG.
lon, lat number The 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 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​

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

Path​

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

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

Example request: Retrieve a static map with a path overlay​

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:

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:

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.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​

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:

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​

Example response: Retrieve a static map with filtered layer​

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​

Static Images API pricing​

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.

Additional Developer Resources