Static Maps

Mapbox Static Maps are optimized for performance and simplicity. Use them to display maps anywhere you can place an image, including in applications or UIs where interactive maps can't be displayed.

Performance

Across different use cases and regions, average load times for Mapbox’s static images are between 100-425ms, which are some of the fastest load times in the industry.

Data Overlays

Add GeoJSON, markers, and paths as overlays to your static maps for quick and simple data visualizations.

Dynamic Map Styles

Add new map layers, change how existing maps are styled, and filter out features from your static map using expressions syntax all at the time of your request.

Fallback for browsers that don’t support WebGL

Use Mapbox.js to provide a consistent fallback experience when a user accesses your map from a browser that does not support WebGL. See how to do this here.

Delivery tracking

Send your users delivery updates that include geographically contextual information on where their packages are.

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 a relevant image that encourages users to click.

Online receipts

Help build trust with your users by giving them an accurate overview of where their purchase took place.

Improve perceived performance of web maps

Use a static image as a quick placeholder while waiting for a GL map to initialize. This allows you to immediately show a user something relevant while your interactive map loads. See a step-by-step tutorial for how to do this here.

Use Cases

Shopify uses the Static Images API in their package tracking app Shop to give their users contextual information on where their packages are as they’re being delivered to them.

Strava uses the Static Images API to transform their text-based news feed into a dynamic activity feed with maps that show summaries of users' actions and encourage others to get active.

Snapchat uses the Static Images API to quickly display users' locations on profile pages. These profile maps are not only fast to load, but also encourage users to further engage, communicate, and interact with each other.

Lyft uses the Static Images API to give their riders an accurate overview of their trips directly in their receipts. These static maps surface just enough information so that users build trust in their Lyft ride experience.

Buzzfeed uses the Static Images API to explore data and unearth journalistic insight that can be used in articles across both web and print.

Yahoo! Japan uses the Static Tiles API to deliver a performant and customized map experience for their users regardless of what device or browser they’re using.

Frequently Asked Questions

General

What is Mapbox 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.

Why is Static Maps helpful?

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.




Use Cases

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:


Compatibility with other Mapbox Products

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.


Comparison with other static map providers

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.

Provider Formats Resolution Max Px Length
Mapbox PNG for styles that contain vector layers
JPG for styles that contain raster layers
@2x too 1280
Apple PNG @2x too 640
CARTO PNG or JPG (default quality of 85) 72 DPI only 8192
Google PNG8, PNG32, JPG, GIF @2x too 640
HERE PNG, JPG, GIF, BMP, PNG8 72 (default), 250 (mobile), 320 (hi-res), or 500 2048
MapQuest PNG, JPG (70, 80, 85, 90), GIF @2x too 1920

Billing

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.




Limitations

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. However, if you require proxying or otherwise redistributing of static images, contact us.
  • 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.

Upcoming Features

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.
  • Request a static image with the Static Images API using a bounding box: as an alternative to providing center coordinates.
  • Set custom padding while using the auto parameter: currently, we provide a default padding size around an overlay when generating a static image. A custom padding parameter would allow for more granular control over how zoomed in the static map is on the map overlay
  • Custom text markers: the ability to add custom text-based markers to the static image you’re requesting.
  • Static Images API URL Builder: a simple web-based tool that allows you to select all of the parameters of the Static Images API you want to use and provides you a template request URL and a map that displays the response from that URL. After designing a map style in Mapbox Studio, you’ll have the option to then use this tool to generate a static image of that style with encoding and string formatting handled for you. The tool will also employ strategies for staying below the URL limit.

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