Static and print maps

Static maps are standalone images (in JPG or 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 API by providing a few parameters, including center coordinates, zoom level, rotation, tilt. Static maps may also include overlays like lines, markers, or polygons.

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

<img src='https://api.mapbox.com/styles/v1/mapbox/streets-v9/static/-122.337798,37.810550,9.67,0.00,0.00/1000x600@2x?access_token=<your access token here>' >

static mapbox map of the san francisco bay area

How static maps work

The Mapbox Static 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, the Retina example above has a width of 1400px and a height of 500px. To take advantage of the sharp Retina image, we used a width attribute that’s half the size of the Retina image’s actual size (700px) in the example above.

High resolution images

With Mapbox Studio and the Mapbox Static API, image exports can be up to 1280x1280 pixels in size. While enabling retina may improve the quality of the image, there are no built-in features to export at a higher resolution, and we do not support vector image formats.

High resolution image exports are possible with Mapbox Studio Classic, however, this process will only work with classic styles. You cannot open styles made with Mapbox Studio in Mapbox Studio Classic to export high resolution images.

Static images for print

If you use a static map in print, you must follow our terms of service. Any Mapbox account allows up to 2,000 print copies for flyers, posters, or short publications per year. For higher quantities, please contact us for our policies and pricing for large volume printing. All print materials must contain the required Mapbox attribution.

You may print any satellite imagery in zoom levels 0-12. To make seamless image files for printing, use Mapbox Studio Classic or the Mapbox Static API with the mapbox.satellite map ID. Dimensions may be up to 1280x1280 pixels. Printing satellite imagery from zoom levels 13-22 is restricted and requires a custom plan - contact sales@mapbox.com for details.

To learn more about printing with Mapbox, see our printing guide.

Creating static maps

You can create a static map from your Mapbox Studio style or a Mapbox template style using Mapbox Studio’s image export tool or by requesting one from the API directly. Below is a list of image formats that are supported and which tools you can use to generate them:

Format Tool(s)
PNG, JPG
via Mapbox Static API
Mapbox Studio
PNG, JPG
via Mapbox Classic Static API
Mapbox Studio Classic
PNG, JPG
high-resolution
Mapbox Studio Classic


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

  • SVG
  • EPS
  • PDF

Mapbox Studio

Mapbox Studio has an interactive image export tool to help you generate a Static API request. From your Styles page, open the menu next to your desired style and click Generate static image. Use the map preview to zoom in and out and pan to the area you want to capture. You can also use the fields on the left to manually adjust the settings. Once you have framed the area you want, copy the URL or HTML from the left-side panel.

demonstration of mapbox studio image export tool

Mapbox Static 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 API documentation for more information about available parameters and values.

Here’s a breakdown of what the URL looks like and what the parameters mean:

explanation of how a static map request is constructed

Overlays

You can add overlays to any maps made with the Static 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 API documentation.

Mapbox Studio Classic and Mapbox Static API (Classic)

You can create a static map from a classic style or a map designed in Mapbox Studio Classic using Mapbox Studio Classic’s image export tool or by making a direct request to the Mapbox Static (Classic) API. The Mapbox Studio Classic export tool also supports high resolution images exports from classic styles.

animation showing how to to export a static image from mapbox studio classic

You can also request a static image of your map by making a direct request to the Mapbox Static API (Classic). See the classic static API documentation for more information about available parameters and values and to learn more about the API’s options including how to add GeoJSON data and markers.

explanation of how a classic static map request is constructed