API overview

This guide will take you through the process of adding a map to your Android app. It assumes you have a Java IDE (like Android Studio) with the Android SDK installed, an application project open, and general familiarity with building User Interfaces in Android. A demo app is available on the Google Play Store that includes all the examples.

App permissions and services

Ensure the following core permissions are requested in your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

If the app is targeting Android Marshmallow (API 23) or later it's necessary to request permissions at runtime.

While your AndroidManifest.xml file is open, you should also include the telemetry service:

<service android:name="com.mapbox.mapboxsdk.telemetry.TelemetryService"/>

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 interatcions, and more.

Lifecycle methods

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:

onCreate();
onResume();
onPause();
onSaveInstanceState();
onLowMemory();
onDestroy();

XML layout

To add the MapView as a layout element, add the following to your xml file:

<com.mapbox.mapboxsdk.maps.MapView
android:id="@+id/mapview"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
mapbox:style_url="@string/style_mapbox_streets"

And then you can call it programmatically within an Activity:

findViewById(R.id.mapview);

Access tokens

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 acitvity onCreate(). In either case you'll need to call the MapboxAccountManager and pass it context and your access token:

  MapboxAccountManager.start(context, <your access token here>);
  

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.

Map styles

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.

Attribution

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.

Supported Android versions

The Mapbox Android SDK is supported for apps running Android API 15 (Ice Cream Sandwich MR1) and above. To ensure that it works in your app, please set minSdkVersion in the App Manifest to no lower than 15.

<uses-sdk android:minSdkVersion="15"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />