Static (Classic)

The classic Mapbox Static API lets you request static maps from tilesets, with the option to add vector data as overlays. Static maps are standalone images that can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map without any interactivity or controls.

If you've uploaded data to Mapbox, you've already seen the classic Static API in action, powering the images at the top of all tileset detail pages.

Swift and Objective-C support for the classic Static API is provided by the MapboxStatic.swift library.

Limits

  • The maximum size for a static map image is 1280x1280 pixels.
  • The URL for a request to this API cannot be longer than 4096 characters.
  • Overlays cannot consist of more than 100 features.
  • Markers must be fewer than 160,000 pixels square (width multiplied by height).
  • Static map images give you design flexibility in how you want to display map attribution. When using Static maps it is your responsibility to add proper attribution for maps in your website or application.

Retrieve a static map image

GET /v4/{map_id}/{overlay}/{position}/{width}x{height}{@2x}.{format}
URL Parameter Description
map_id unique identifier for the tileset in format username.id . These can be a comma-separated list of IDs.
overlay
(optional)
one or more comma-separated features to draw on top of the map. These can be in marker , geojson or path format.
position center and zoom level for the map. You can use auto to automatically fit image to overlay features, or {lon},{lat},{zoom} to set a specific location and zoom
width width of the image in pixels
height height of the image in pixels
format format of the image

The support formats are the same as for the Mapbox Maps API:

Image format Description
png True color PNG
png32 32 color indexed PNG
png64 64 color indexed PNG
png128 128 color indexed PNG
png256 256 color indexed PNG
jpg70 70% quality JPG
jpg80 80% quality JPG
jpg90 90% quality JPG

The {overlay} parameter can specify one or more features to draw on top of the map. The list of features should be comma-separated. Each overlay feature can be in one of three formats: marker, geojson or path.

Marker

{name}-{label}+{color}({lon},{lat})
URL Parameter Description
name Marker shape and size. Options are pin-s , pin-m , pin-l .
label
(optional)
Marker symbol. Options are an alphanumeric label a through z , 0 through 99 , or a valid Maki icon.
color
(optional)
A 3- or 6-digit hexadecimal color code.

Custom marker

url-{url}({lon},{lat})
URL Parameter Description
url a percent-encoded URL for the image

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

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

GeoJSON

geojson({geojson})

The {geojson} argument must be a valid GeoJSON object. simplestyle-spec styles for GeoJSON features will be respected and rendered.

geojson({geojson})
URL Parameter Description
geojson a valid GeoJSON object. simplestyle-spec styles for

GeoJSON features will be respected and rendered.

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.

URL Parameter Description
strokeWidth
(optional)
Positive number for 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
polyline A valid encoded polyline encoded as a URI component

Example Request

# without an overlay
curl "https://api.mapbox.com/v4/mapbox.dark/-76.9,38.9,5/1000x1000.png?access_token={your_access_token}"

# as a jpg file
curl "https://api.mapbox.com/v4/mapbox.satellite/-76.9,38.9,5/1000x1000.jpg?access_token={your_access_token}"

# as a 32 color indexed png file
curl "https://api.mapbox.com/v4/mapbox.dark/-76.9,38.9,5/1000x1000.png32?access_token={your_access_token}"

# with a custom marker overlay
curl "https://api.mapbox.com/v4/mapbox.dark/url-https%3A%2F%2Fmapbox.com%2Fimg%2Frocket.png(-76.9,38.9)/-76.9,38.9,15/1000x1000.png?access_token={your_access_token}"

# with a polyline overlay
curl "https://api.mapbox.com/v4/mapbox.streets/path-5+f44-0.5+f44-0.2(kumwFrjvbMaf%40kuD%7BnCkS)/-73.99,40.70,12/500x300.png?access_token={your_access_token}"

# with a geojson overlay
curl "https://api.mapbox.com/v4/mapbox.streets/geojson(%7B%22type%22%3A%22Point%22%2C%22coordinates%22%3A%5B-73.99%2C40.7%5D%7D)/-73.99,40.70,12/500x300.png?access_token={your_access_token}"
# without an overlay
>>> from mapbox import Static
>>> service = Static()
response = service.image('mapbox.satellite', lon=-61.7, lat=12.1, z=12)

# with a GeoJSON overlay
portland = {
...    'type': 'Feature',
...    'properties': {'name': 'Portland, OR'},
...    'geometry': {
...        'type': 'Point',
...        'coordinates': [-122.7282, 45.5801]}}
response = service.image('mapbox.satellite',
...     features=[portland, bend])

# add to a file
with open('/tmp/output_file.png', 'wb') as output:
...     _ = output.write(response.content)
# without an overlay
mapbox staticmap --lat "-39.2978" --lon "174.0632" --zoom 13 --size 800 800 mapbox.satellite output_file.png

# with a GeoJSON overlay
mapbox staticmap --features waypoints.geojson mapbox.streets output_file.png
// This API cannot be accessed with the JavaScript SDK
// This API cannot be accessed with the Mapbox Java SDK
@import MapboxStatic;

CLLocationCoordinate2D coordinate = CLLocationCoordinate2DMake(45.52, -122.681944);
// Dimensions are measured in resolution-independent points.
CGSize size = CGSizeMake(200, 200);
MBClassicSnapshotOptions *options = [[MBClassicSnapshotOptions alloc] initWithMapIdentifiers:@[@"mapbox.satellite"] centerCoordinate:coordinate zoomLevel:13 size:size];

MBSnapshot *snapshot = [[MBSnapshot alloc] initWithOptions:options accessToken:@"<#your access token#>"];

// Retrieve the image synchronously, blocking the calling thread.
// `image` is a `UIImage` on iOS, watchOS, and tvOS and an `NSImage` on macOS.
self.imageView.image = snapshot.image;

// Alternatively, pass a completion handler to run asynchronously on the main thread.
[snapshot imageWithCompletionHandler:^(UIImage * _Nullable image, NSError * _Nullable error) {
    self.imageView.image = image;
}];
import MapboxStatic

let options = ClassicSnapshotOptions(
  mapIdentifiers: ["mapbox.satellite"],
  centerCoordinate: CLLocationCoordinate2D(
    latitude: 45.52,
    longitude: -122.681944),
  zoomLevel: 13,
  // Dimensions are measured in resolution-independent points.
  size: CGSize(width: 200, height: 200))

// If Snapshot conflicts with another class in your module, use `MapboxStatic.Snapshot`.
let snapshot = Snapshot(
  options: options,
  accessToken: "<#your access token#>")

// Retrieve the image synchronously, blocking the calling thread.
// `image` is a `UIImage` on iOS, watchOS, and tvOS and an `NSImage` on macOS.
imageView.image = snapshot.image

// Alternatively, pass a completion handler to run asynchronously on the main thread.
snapshot.image { (image, error) in
    imageView.image = image
}