Skip to main content

Snapshotter

A newer version of the Maps SDK is available
This page uses v9.7.1 of the Mapbox Maps SDK. A newer version of the SDK is available. Learn about the latest version, v11.8.1, in the Maps SDK documentation.

The snapshot functionality of the Mapbox Maps SDK for Android generates a static map image to use in your Android project. Take a snapshot of any Mapbox map and add the image into:

  • another screen in your app
  • a home screen
  • a home screen widget
  • a notification
  • a ListView/RecyclerView
  • wherever else a Bitmap can be placed

A Mapbox map doesn't need to be displayed to use the snapshot functionality. MapSnapshotter can be invoked anywhere in the app.

Unless you have the map tiles already cached, the device will need an internet connection to download the style and tiles necessary to render the map, and thus, the snapshot.

Snapshot generation can happen on the device's background thread and won't compromise the user experience.

This snapshot feature is different than the Mapbox Static Images API. The MapboxStaticMap class helps you build a URL to request a static map image which looks like an embedded map without interactivity or controls.

Taking a map snapshot

The MapSnapshotter constructor requires a MapSnapshotter.Options object.


MapSnapshotter.Options snapShotOptions = new MapSnapshotter.Options(500, 500);

snapShotOptions.withRegion(mapboxMap.getProjection().getVisibleRegion().latLngBounds);

snapShotOptions.withStyle(mapboxMap.getStyle().getUrl());

MapSnapshotter mapSnapshotter = new MapSnapshotter(this, snapShotOptions);

Here are the various settings that are available within the MapSnapshotter.Options class. You would use them in the same way that withRegion() and withStyle() are used in the code snippet above.

MethodDescription
withApiBaseUrlSpecifies the URL used for the Maps API endpoint. It's rare that you'll need to change the API base URL.
withLocalIdeographFontFamilySet the font family for generating glyphs locally for ideographs in the "CJK Unified Ideographs" and "Hangul Syllables" ranges.
withCameraPositionThe camera position to use for the snapshot image. This position is overridden if withRegion is also used.
withLogo A boolean flag to determine whether the Mapbox logo is included in the snapshot image.
withPixelRatio The pixel ratio to use. The default is 1.
withRegion The region to show in the snapshot image. This is applied after the camera position.
withStyle The map style to use in the snapshot image.
withStyleJson The map style JSON to use instead of a map style URL.

Start the snapshot process with start() once you've created your MapSnapshotter object. When MapSnapshot is ready, use snapshot.getBitmap() to retrieve the Bitmap image.


mapSnapshotter.start(new MapSnapshotter.SnapshotReadyCallback() {
@Override
public void onSnapshotReady(MapSnapshot snapshot) {

// Display, share, or use bitmap image how you'd like

Bitmap bitmapImage = snapshot.getBitmap();



}
});

Once you have the Bitmap image, you're free to use it how you'd like.

The Mapbox Android demo app has two examples that show how the snapshot Bitmap images can be used:

EXAMPLE
Share snapshot image

Share the real-time map snapshot image.

EXAMPLE
Display a snapshot notification

Use the map snapshot image in a notification.