This guide will take you through the process of adding a map to your Android app. It assumes you have an IDE
like Android Studio with
the Android SDK installed,
an application project open, and general familiarity with building apps.
A demo app is available on the Google Play Store that
includes all the examples.
MapView and MapboxMap
MapView and MapboxMap are the key components of the Mapbox Android SDK. MapView behaves like any other View and its behavior can be changed statically with an XML layout file, or programmatically during runtime. You can think of MapboxMap as the controller class for your map. It includes methods to set and move the camera position, add markers, configure user interactions, and more.
The MapView contains its own lifecycle methods for managing Android's OpenGL lifecycle that must be called directly from the containing Activity. In order for your app to correctly call the MapView's lifecycle methods, you must override the following lifecycle methods in the Activity that contains the MapView:
To add the MapView as a layout element, add the following to your xml file:
And then you can call it programmatically within an Activity:
An access token is necessary to use Mapbox services and APIs, such as maps, directions, and geocoding. Your access tokens can be managed in your account settings, where you can retrieve current tokens and generate new ones. You should create a new token for each of your apps, which will help you track usage and minimize disruption in the event a token needs to be revoked.
There are two places to provide an access token in your app. If you are using a custom application object, you can place it in the onCreate() or it can go in your applications launch activity onCreate(). In either case you'll need to call the MapboxAccountManager and pass it context and your access token:
Telemetry opt out
Mapbox Telemetry is a powerful location analytics platform included in this SDK. By default, anonymized location and usage data is sent to Mapbox whenever the host app causes it to be gathered. The Mapbox Terms of Service require your app to provide users with a way to individually opt out of Mapbox Telemetry, which is provided automatically as part of the attribution control. If you hide the attribution control, you must provide an alternative opt out for your users to use.
The Mapbox Android SDK is designed to work with the custom styles you create in Mapbox Studio, but also comes bundled with five professional styles that will look great in your app:
Mapbox Streets: Mapbox Streets is a comprehensive, general-purpose map that emphasizes accurate, legible styling of road and transit networks.
Outdoor: Mapbox Outdoors is a general-purpose map with curated datasets and specialized styling tailored to hiking, biking, and the most adventurous use cases..
Light and Dark: Mapbox Light and Mapbox Dark are subtle, full-featured maps designed to provide geographic context while highlighting the data on your analytics dashboard, data visualization, or data overlay.
Satellite: is our full global base map that is perfect as a blank canvas or an overlay for your own data.
Satellite Streets: combines our Mapbox Satellite with vector data from Mapbox Streets. The comprehensive set of road, label, and POI information brings clarity and context to the crisp detail in our high-resolution satellite imagery.
To use a custom style, paste your style URL into your MapView's mapbox:style_url attribute in your activity's layout file. If you would like to change the map style later on, call MapboxMap.setStyleUrl() with the new style and your map will update.
You must comply with the licensing terms of any map data in your application, including Mapbox Streets or other Mapbox maps if used. A small attribution control will be displayed on the map view automatically. The attribution control may be moved or removed as necessary, so long as the required attribution is reasonably provided in your app.
For more information on Mapbox’s attribution requirements, click here.
Include Mapbox Android Services in your application
An SDK for Mapbox's wide range of services, including directions,
geocoding, map matching, and static map imagery - built for both Android and
pure Java applications.
Mapbox Java Services is a dependency-free, low-level set of utilities for
interacting with Mapbox & solving geospatial problems - perfectly suited
for server or desktop applications. Mapbox Android Services builds on that
base, helping you get projects off the ground faster by providing views for
Android applications, including autocompletion for geocoding.
Our Help page is filled with how-to references and guides so you can master our tools.