Static Maps

Mapbox Static Maps is a collection of HTTP APIs and client libraries that generate static images of GL-based map styles as either PNG or JPEG files.

Static Maps consists of two HTTP APIs:

• Mapbox Static Images API: serves standalone, static map images generated from Mapbox Studio styles of up to 1280x1280 pixels. These images can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map, but do not have interactivity or controls. For styles that contain vector layers, the returned static map will be a PNG, and for styles that contain raster layers, the returned static map will be a JPEG.
• Mapbox Static Tiles API: serves raster tiles generated from Mapbox Studio styles. Raster tiles can be used in traditional web mapping libraries like Mapbox.js and Leaflet to create interactive slippy maps. The returned raster tile will be a JPEG, and will be 512x512 pixels by default.

and three client libraries:

• Mapbox.js: a plugin for the mapping library Leaflet and a JavaScript wrapper to the Static Tiles API. This library is used to create raster-based slippy maps with simple data overlays.
• MapboxStatic.swift: a Swift wrapper to the Static Images API. This library is used to create stand-alone map images and data overlays in Swift-based iOS applications.
• The Mapbox Java SDK: a Java wrapper to many Mapbox APIs, including the Static Images API. This library is used to create stand-alone map images and data overlays in Java-based Android applications.

The main value propositions for Static Maps are performance and simplicity. You can use Static Maps to create fully-featured maps without very many lines of code and oftentimes with just an HTML image tag. This means you don’t need to learn, load or use a complex mapping library or SDK.

Static Maps can be displayed anywhere that images might be, including in applications or UI contexts where interactive maps cannot be integrated. These include: emails, app notifications, articles for both web and print, low-power devices, and more.

Static maps are images that can be used in a wide variety of use cases:

• Delivery tracking: send your users delivery updates that include geographically contextual information on where their packages are.
• Online receipts (e.g. for ride-sharing, on-demand delivery, and e-commerce): help build trust with your users by giving them an accurate overview of where their purchase took place.‍
• Mobile notifications: create contextually personalized notifications. When combined with a customized map style, notifications go from a single line of text that’s likely to get lost in a sea of notifications to an intrinsically relevant image that encourages users to click.‍
• Fitness activity feeds: transform a text-based news feed into a dynamic activity feed with maps that show users summaries of their actions that encourage others to get active.‍
• Social media profile maps: use Static Maps in users’ profile pages to provide contextual info about users that will encourage them to further engage, communicate, and interact with each other ‍
• News maps for web and print: use Static Maps to create news articles with maps that can be used across both web and print.‍
• ‍Improve perceived performance of web maps: use Static Maps to generate a static placeholder while waiting for a GL map to initialize. This allows you to immediately show a user something while your GL map loads. See an example here.‍
• Fallback for browsers that don’t support WebGL: Use Static Maps to provide a consistent fallback experience when a user accesses your map with a browser that does not support WebGL. See how to do this here.

Static maps are fixed and do not change based on user interaction or real-time data. They are typically printed on paper or displayed as images in apps and websites. Dynamic maps are interactive maps that can be manipulated and customized by users and can incorporate real-time data feeds to show things like traffic patterns or weather conditions.

You can read documentation for each component of Mapbox Static Maps below:

• HTTP: Static Images API,Static Tiles API
• JavaScript: Mapbox.js
• iOS: MapboxStatic.swift‍
• Android: Mapbox Java SDK

When should I use Static Maps instead of Mapbox GL JS or the Mapbox Mobile Maps SDKs?

Generally, the main reason to use Static Maps over GL is performance—specifically Static Maps is helpful in improving initial perceived render performance for GL-based slippy maps, improving performance of displaying multiple GL contexts on the same page, and/or displaying small maps with simple data overlays. Static Maps can be more performant in these situations because loading multiple or even just one GL map requires work from a CPU/GPU, whereas using Static Maps solely involves more network/HTTP activity for your application.

Additionally, you can use Static Maps to provide a fallback slippy map for browsers and devices that don’t support GL.

Use cases where client-side GL is more favorable to use than Static Maps are described in the Limitations section of this FAQ.

‍

What’s the difference between Static Maps and the Mapbox Map Snapshotter for iOS and Android?

Both Mapbox Static Maps and the Mapbox Map Snapshotter can be used to generate static images of GL-based map styles for use in mobile applications; however, Static Maps generates its images server-side before delivering those images to clients, while the Mapbox Snapshotter generates its images client-side after initializing the Mapbox Maps SDK and requesting the necessary map style(s) and tileset(s).

‍

When should I use Static Maps vs the Map Snapshotter?

If you want to generate a static image from a GL-based style that is already loaded in your mobile application, then it’s likely more performant to generate your static image client-side using the Map Snapshotter given you will already have all the resources you need locally to generate the static image.

If you want to generate a static image in a part of your mobile application that doesn’t use the Mapbox Maps SDK or that doesn’t already have a GL-based style loaded, then it’s likely more performant to use Static Maps to generate your static image server-side. This is because Static Maps don’t require loading a mapping library like GL or other client-side SDK before being able to generate a map and Static Maps has optimized, low latency access to all the resources needed to render the map. Static Maps can always stay inside the AWS network for getting resources unlike a mobile client which needs to go over the public internet to get resources.

‍

What types of map styles is Static Maps compatible with?

You can use Static Maps to generate static images of any map styles that follow the Mapbox GL Style Specification. This includes any styles created in Mapbox Studio or directly with the Mapbox Styles API v1.

‍

How long does it take for changes I make to my map style to be reflected in Static Maps?

It can take up to 12 hours for your map changes to be reflected based on the default caching behavior of Static Maps.

‍

Are all the styling capabilities in GL JS or Mapbox Studio available with Static Maps?

Not initially. While we aim for styling parity between what’s available in GL JS and Mapbox Studio and Static Maps, it can take some time for new styling functionality that’s available in GL JS or Studio to also be available with Static Maps. If you have specific styling functionality you would like to see added to Static Maps, please let us know.

How does Mapbox Static Maps compare to other static map providers?

Performance

Mapbox is consistently more performant than other static map providers across various regions and use cases.

Overlays: 100 Markers & Path of 100 Points

Image Sizes: Small=180x144, Medium=1280x1024

Resolution: Normal, @2x

Regions: Los Angeles, London, Frankfurt, Tokyo, Hong Kong

Across different use cases and regions, average load times for Mapbox’s static images are between 100-200ms and 425ms depending on whether the image is already cached or not.

‍

Overlay Support

Mapbox supports markers, paths with fills, and unlike other providers, GeoJSON overlays on static maps. This enables much more customization and flexibility when adding overlays on static maps. Circles can also be added as an overlay for Static Tiles via extended functionality from Leaflet.

‍

Dynamic Map Styles

Google is the only other static map provider that allows you to change the style of a static map at request time, but that functionality is limited to either hiding a map feature or changing its color. No other static map provider offers the same level of static map customization as Style Parameters with the Static Images API.

addlayer: use this parameter to add new style layers to your map and change how existing layers are styled. Using this feature, you can do things like change the color of all states or extrude all buildings in their map based on a shared attribute, such as presidential election results or proximity to a flood zone.

setfilter: this parameter accepts an array value that adheres to Mapbox's expressions syntax. Use this parameter to filter out features from an existing style layer. For example, if you’re building an app that helps people find running, hiking, or mountain biking paths, you can filter out all roads and paths from your map, except for the paths a user needs for the type of activity they are interested in.

‍

Image Details

Mapbox offers support of PNG and JPEG image formats, at up to @2x resolution, and 1280x1280 max pixel length.

‍

What pricing is available with Static Maps?

Static Maps is billed by individual API request for the Static Images and Static Tiles API. The Static Images API is free up to 50K requests per month then starts at $1.00 per 1,000 requests with incremental volume-based discounts available for usage over 500K, 1M, and 5M requests per month.

The Static Tiles API is free up to 200K requests per month then starts at $0.50 per 1,000 requests with incremental volume-based discounts available over 2M, 4M, and 20M requests per month.

You can see more pricing information at https://www.mapbox.com/pricing/.

‍

Do the pixel sizes of the static images I request impact the price I pay per request?

No. Pricing for both the Static Images API and Static Tiles API is agnostic of the dimensions of the request.

What are the service limits of Static Maps?

Use of the Static Images API and Static Tiles API is rate limited with a default rate limit of 1,200 requests per minute and 5,000 requests per minute, respectively. Exceeding these limits will result in an HTTP 429 response. However, if you require a higher rate limit, contact us.

‍

What are the functionality-related limitations of Static Maps?

• Feature Interactivity: Because Static Maps generates image files, the rendered maps inherently lack the same type of feature interactivity available with vector-based GL maps that can use a client’s GPU for enhanced rendering functionality.
• Dynamic, Client-Side Re-styling & Data Visualization: While you can use style parameters with Static Maps to change the requested map style at request time, large-scale client-side re-styling and data manipulation will likely be more efficient with Runtime Styling and Mapbox GL expressions on the client.
• Rotated/Pitched View Slippy Maps: The Static Tiles API does not support rotation or pitched views (e.g. as is used in turn-by-turn navigation); however, the Static Images API does support rotating and pitching the map.
• Smooth Zooming: Static Maps only generates static images at each integer zoom level, meaning as you zoom in and out of slippy maps made with the Static Tiles API, you’ll likely notice a “jump” between zoom levels. This “jump” isn’t apparent with vector-based slippy maps as they offer “smooth zooming” with non-integer zooms levels.
• Cut-off labels: Because the Static Tiles API renders images for its slippy maps one tile at a time as opposed to continuously like with a vector-based map, there is a small probability that any map labels placed at or near tile boundaries will be partially cut-off. Use of GL features that enable dynamic, variable or otherwise non-deterministic label placement, or increased label density can both increase the rate of cut-off labels with the Static Tiles API. If using Static Maps with one of Mapbox’s Core Styles, then you can expect <2% of your map labels to be cut-off in any region. If using Static Maps with a custom style, then you can expect <5% of your map labels to be cut-off in any region.
• URL length limit: much of the functionality of Static Maps—including styling, orienting, and adding overlays to the map—is made available via GET HTTP requests. This means all functionality of Static Maps is limited by the 8,192 byte URL length limit.

‍

What are the use case-based limitations of Static Maps?

• Proxying and Redistribution   
  All requests to Static Maps must be generated by an end-user device. If any requests to are generated by a server, the resulting images cannot be later redistributed to end-user devices.
  

• Caching 
  The static images returned by the Static Images API and Static Tiles API can only be cached on client devices for up to 30 days. However, if you require caching static images for longer than 30 days, contact us.
  

• Printing 
  Printing of static images is only permitted for personal, non-commercial use. When using a map style that incorporates the mapbox-streets-v8  tileset, printing of static images that include Japan is not allowed. However, if you require printing of static images that include Japan, and/or for a commercial use case, contact us.
  

What are some upcoming features of Static Maps?

We are currently evaluating customer demand for the following features in 2020:

• Map Loads pricing for the Static Tiles API: When using Mapbox.js, pay for the Static TIles API per map load instead of per tile request.
• Support for @4x resolution: request static images at up to a @4x scale factor for high-resolution displays.
• Custom text markers: the ability to add custom text-based markers to the static image you’re requesting.‍
• Support for 3D Static Images: request static images for styles that include 3D style rules

‍

If any of these features sound interesting to you, please let us know!

The Static Image Playground is an interactive web application that can be used to prototype requests against the Static Images API. It allows you to create a valid request against the Static Images API without installing any SDKs or writing any additional code.

Yes. The Static Image Playground includes support for all possible functionality of the Static Images API. These include:

• Build image requests with custom styles created by Mapbox Studio.
• Add multiple marker, path, and GeoJSON overlays to your Static Image request.
• See the results of “auto” positioning when used with overlay data.
• Generate a map image based on a bounding box rather than a center coordinate pair.
• Adjust the visual padding of the map image for all or some of the sides of the image.

Per our documentation, a valid overlay can be a Geojson, a marker or an encoded path. You will receive an error if you enter an invalid entry in the overlay input entry.

The Static Image Playground is the ideal tool for prototyping your Static Images API requests. Use it to learn what the full breadth of what the Static Images API is capable of, and how each feature behaves. It’s great for both beginners trying to learn more about the API’s capabilities and experienced developers who need to debug their requests visually.

The Static Image Playground is a responsive web application that can be accessed on any device with a modern web browser. You can prototype Static Images API requests from your desktop, tablet, or mobile device.

Requests made within the Static Image Playground application will not generate Static Images API usage associated with your account. However, after you have constructed your request URI, if you incorporate this URI within an application or make requests directly against it, these requests will generate billable usage.

The Static Image Playground does not grant programmatic access to its interface, or lend itself to programmatic generation of Static Images API requests at this time. If you are looking for a tool that can be directly incorporated into your application, we strongly recommend mapbox-sdk.js or one of its counterparts.