FAQ

What are the supported use cases of Static Maps?

• 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.

How can I use Static Maps?

You can read documentation for each component of 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.