You are viewing documentation for an older version of the Mapbox API. Check out v4 for the latest.

Static maps

Static maps are standalone images that can be displayed on web and mobile devices without the aid of a mapping library or API. A static map image uses the Mapbox {mapid} and looks like an embedded map without any interactivity or controls.

Each static map image counts as 1 map view.


Request an image of size {width}x{height} (in pixels) for a given {mapid}. The {lon},{lat},{z} parameters define the center of the static map image. The {lon} and {lat} coordinates range from -180 to 180 and -85 to 85 using a decimal separator. {z} must be an integer between the minzoom and maxzoom supported by the map. The image {format} defaults to png but can be used to adjust the image quality, format, and scale factor.

The optional {markers} parameter can include one or more markers in a comma-separated list. See the Markers section for options.

Image quality & retina

The {format} of any image request can be replaced by any of the following extensions to adjust image quality for different bandwidth requirements. Mapbox reencodes the output image based on the requested format.

For maps that support retina autoscaling, indicated by "autoscale": true in a map's TileJSON, you can prefix any image quality type with @2x to request a high DPI version.

@2x.png2x scale (retina)
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

Size limit

The maximum size for a static map image is 1280x1280. This absolute pixel size limit does not change when using the @2x suffix making the max size for retina images 640x640.


Static map images give you design flexibility in how you want to display map attribution. When using Static maps it is your responsibility to ensure proper attribution of maps (e.g. to OpenStreetMap contributors) in your website or application.



The {markers} parameter of static maps can specify one or more markers to add to the map. The list of markers (max: 100) should be comma-separated. Each marker requires the {name}, {lon} and {lat} parameters. The {label} and {color} parameters may be omitted to use default settings.

name Marker shape and size.
pin-s, pin-m, pin-l
label Marker symbol. An alphanumberic label or valid Maki icon.
a-z, 0-9,
color An 3 or 6 digit RGB hex color.

Custom markers


Request an external marker image by specifying its URL. Use a percent encoded URL for the {url} parameter. If the url protocol is omitted the external marker will be assumed to use http://. Custom markers are cached according to the Expires and Cache-Control headers. Make sure that at least one of these headers is set to an appropriate value to prevent repeated requests for the custom marker image.

The marker image is always centered on the specified location, so when creating an asymmetric marker (like a pin), make sure that the tip of the pin is at the center of the image.

Maximum size for custom marker images is 8192 pixels (width x height).

Stand-alone markers{name}-{label}+{color}.png{name}-{label}+{color}@2x.png

Request a single marker without any background map. These markers can be used to display data client-side in a JavaScript API or mobile API to add images to your map.