Legacy Static Images

Note

The classic Static API is a legacy product. It is no longer in active development. To learn more about Mapbox's newer web services APIs see the modern Static API documentation.

The Legacy Static Images 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 Legacy Static Images API in action, powering the images at the top of all tileset detail pages.

Swift and Objective-C support for the Legacy Static Images 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 in your website or application.

Retrieve a static map image

get
/v4/{tileset_id}/{overlay}/{position}/{width}x{height}{@2x}.{format}
URL ParameterDescription
tileset_idunique 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.
positioncenter 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
widthwidth of the image in pixels
heightheight of the image in pixels
formatformat of the image

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

Image formatDescription
pngTrue color PNG
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

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 ParameterDescription
nameMarker 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 ParameterDescription
urla percent-encoded URL for the image

Custom markers are cached according to theExpires 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 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. Note that # characters must be replaced in the URL with %23 (for example, "fill":"#FF0000" would be "fill":"%23FF0000").

geojson({geojson})
URL ParameterDescription
geojsona 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 ParameterDescription
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
polylineA 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%2Fwww.mapbox.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
}