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. Learn how to build a Static API request using the Static API playground.
The image below was generated using the Mapbox Static API and can be added to a web page using the following code:
<img alt='static Mapbox map of the San Francisco bay area' src='https://api.mapbox.com/styles/v1/mapbox/streets-v10/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, 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 a limited number of high resolution image exports per account using the print panel. The number of print exports permitted for your account is based on plan level:
|Plan level||Available image exports per account (total)|
With the Mapbox Static 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 API, and we do not support vector image formats.
Static images for print
If you use a static map in print, you must follow our terms of service:
- Non-commercial uses: You may make static exports and prints for non-commercial purposes such as flyers, posters, or other short publications for academic, non-profit, or personal use.
- Commercial uses: Commercial printing requires a custom plan, please contact our team for pricing.
- Attribution: All static and print materials for both commercial and non-commercial uses must contain the required Mapbox attribution.
Creating static maps
Below is a list of image formats that are supported and which tools you can use to generate them:
|PNG||Mapbox Static API|
|Mapbox Studio (limited number of exports per account)
Mapbox Studio Classic
via Mapbox Classic Static API
|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 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.
Mapbox Static API playground
To learn how to build a Static API request, check out the Mapbox Static API playground.
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.
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 ppi), 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.
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.