How Mapbox works

Static and print maps

Static maps are standalone images in PNG format 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 interactivity or controls. You can request a static map from the Mapbox Static Images API by providing a few parameters, including center coordinates, zoom level, rotation, and tilt. Static maps may also include overlays like lines, markers, or polygons. Learn how to build a Static Images API request using the Static Images API playground.

The image below was generated using the Mapbox Static Images API and can be added to a webpage using the following code:

<img alt='static Mapbox map of the San Francisco bay area' src='https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/-122.337798,37.810550,9.67,0.00,0.00/1000x600@2x?access_token=YOUR_MAPBOX_ACCESS_TOKEN' >

How static maps work

The Mapbox Static Images API allows you to request a static image representation of any map style in your Mapbox account. You can retrieve a static map in a few different image and file formats depending on the Mapbox tool you are using. See How to create a static map below for more information on supported file types.

Retina

When you request a Retina map with @2x, you will receive an image that's twice the width and height that you've specified in your API call. For example, using a width attribute of 700 px with the @2x parameter will return an image with an actual width of 1,400 px.

High resolution images

Mapbox Studio offers 100 high resolution image exports per account using the print panel. If you are interested in having a higher number of allowed image exports, contact Mapbox sales.

With the Mapbox Static Images API, image exports can be up to 1,280 px x 1,280 px in size. While enabling retina may improve the quality of the image, you cannot export at a higher resolution using the Static Images API, and we do not support vector image formats.

Static images for print

To print images generated from the Mapbox Studio print export option for any use, contact us. Print maps require appropriate Mapbox attribution.

Creating static maps

Below is a list of image formats that are supported and which tools you can use to generate them:

FormatTool(s)
PNGMapbox Static Images API
PNG, JPG
high-resolution
Mapbox Studio (limited number of exports per account)

The following formats are not supported as a map export option and are not on our road map for integration:

  • SVG
  • EPS
  • PDF

Mapbox Static Images API

You can get a static image of your map by formatting a URL with your specific values to make the request. See the Mapbox Static Images API documentation for more information about available parameters and values.

Mapbox Static Images API playground

To learn how to build a Static Images API request, explore the Mapbox Static Images API playground.

screenshot of the Static Images API playground page

Overlays

You can add overlays to any maps made with the Static Images API. An overlay is data that can be added on top of the map at request time. Overlays are comma separated and can be a mix of valid GeoJSON, custom markers, paths, or polygons. Read more about how to add an overlay to a static map in our Static Images API documentation.

Mapbox Studio

The Mapbox Studio print panel allows you to export high resolution images of custom map styles. Click the printer icon to toggle the print panel on and off. Position your map and specify Print export settings in the print panel. Settings include image dimensions (in inches or centimeters), resolution (in pixels per inch), and file format (PNG or JPG). The maximum image export is 8,000 px by 8,000 px.

Read more about the print panel in the Mapbox Studio manual.

screenshot of the print panel with print export settings as described above

Was this page helpful?