Supports API level 15 or higher

Add Mapbox to your Android app

Add Mapbox as a dependency to your build.gradle file:

repositories {
    mavenCentral()
}

dependencies {
    compile ('com.mapbox.mapboxsdk:mapbox-android-sdk:4.2.1@aar'){
        transitive=true
    }
}

Add the nightly build of Mapbox as a dependency to your build.gradle file:

repositories {
    mavenCentral()
    maven { url "http://oss.sonatype.org/content/repositories/snapshots/" }
}

dependencies {
    compile ('com.mapbox.mapboxsdk:mapbox-android-sdk:5.0.0-SNAPSHOT@aar') {
        transitive=true
    }
}

Required configuration

Permissions

Add the following required permissions to AndroidManifest.xml:

<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" />

Add the required telemetry service to AndroidManifest.xml:

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

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

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" />

API overview

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.

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

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.

  1. Add Mapbox Android Services as a dependency to your build.gradle file:

    repositories {
        mavenCentral()
    }
    
    dependencies {
        compile ('com.mapbox.mapboxsdk:mapbox-android-services:1.3.1@aar'){
            transitive=true
        }
    }
  2. Add android.permission.INTERNET to your AndroidManifest.xml:

    <uses-permission android:name="android.permission.INTERNET" />
  1. Add Mapbox Android Services as a dependency to your build.gradle file:

    repositories {
        mavenCentral()
        maven { url "http://oss.sonatype.org/content/repositories/snapshots/" }
    }
    
    dependencies {
        compile ('com.mapbox.mapboxsdk:mapbox-android-services:2.0.0-SNAPSHOT@aar') {
            transitive=true
        }
    }
  2. Add android.permission.INTERNET to your AndroidManifest.xml:

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

Add Mapbox Java Services as a dependency to your build.gradle file:

repositories {
    mavenCentral()
}

dependencies {
    compile ('com.mapbox.mapboxsdk:mapbox-java-services:1.3.1@jar') {
        transitive=true
    }
}

Add Mapbox Java Services as a dependency to your build.gradle file:

repositories {
    mavenCentral()
    maven { url "http://oss.sonatype.org/content/repositories/snapshots/" }
}

dependencies {
    compile ('com.mapbox.mapboxsdk:mapbox-java-services:2.0.0-SNAPSHOT@jar'){
        transitive=true
    }
}

Features

Mapbox Android Services provide all the parts you need to complete your application: integration with Mapbox APIs, geospatial analysis utilities, and more:

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.

Need help?

Our Help page is filled with how-to references and guides so you can master our tools.