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>' >
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.
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 email@example.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:
via Mapbox Static API
via Mapbox Classic Static API
|Mapbox Studio Classic|
|Mapbox Studio Classic|
The following formats are not supported as a map export option and are not currently on our road map for integration:
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.
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:
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.
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.