First steps with the Mapbox Maps SDK for Android
Completion of the Mapbox Maps SDK for Android installation process and familiarity with Android Studio and Java.

The Mapbox Maps SDK for Android is our vector maps library for Android. This guide will walk you through installing the Mapbox Maps SDK for Android with Android Studio, loading a map, changing the map’s style, and placing a pin on it.

map with marker and info window on an Android device

Getting started

Here’s what you’ll need to get started:

  • A Mapbox account and access token. Sign up for an account at You can find your access tokens on your Account page.
  • Android Studio. You can download Android Studio for free from Google. In order to install the Mapbox Maps SDK for Android, you’ll need to first download Android Studio and create a project with an empty activity.
  • An Android device (physical or virtual). You will need either a physical Android device or an emulated Android device to preview the store finder.
  • Google Play Developer Account (optional). If you want to publish your app to Google Play, you’ll need a Google Play developer account. Without one, you’ll still be able to preview the app on an Android Virtual Device (AVD) or install the app on a physical device.

Create an Android Studio project

Familiarize yourself with Android Studio. You’ll need to create a new project with an empty activity. Use the following options when creating a new Android Studio project:

  • Under Select the form factors your app will run on, check “Phone and Tablet.”
  • For minimum SDK, select API 14: Android 4.0.0 (IceCreamSandwich). (This is the lowest API level currently supported by Mapbox Maps SDK for Android.)
  • Click Next to advance to the activity selection screen.
  • Select Empty Activity and click Next.
  • Accept the default Activity Name and Layout Name and click Finish.

If you need help installing Android Studio or creating your first project, see the Android Studio documentation.

Set up a virtual device

With Android Studio, you can set up virtual Android devices on your computer to test your app while you develop. To set up a virtual device, click on the Android Virtual Device (AVD) Manager icon icon for AVD in the Android Studio interface, then click the Create Virtual Device button. You can also get to the manager via Tools > Android > AVD Manager in the toolbar. From the Phones category, select Nexus 5X and click Next. Select the release you would like to test against (this guide was built using API level 26).

Learn more about setting up an AVD in the Android Studio documentation.

Install the Mapbox Maps SDK for Android

Before you begin building your app, install the Mapbox Maps SDK for Android by following our installation guide. The installation guide assumes that you have already downloaded Android Studio and created a new project. You’ll make changes to four different files within your project to install the Mapbox Maps SDK for Android. The four files you’ll be working with include:

  • build.gradle (Module:App): Android Studio uses a toolkit called Gradle to compile resources and source code into an APK. This plain text file is used to configure the build and list dependencies, including the Mapbox Maps SDK for Android.
  • AndroidManifest.xml: This is where you’ll describe components of the application, including Mapbox-related permissions.
  • This is a Java file where you’ll specify Mapbox classes and methods.
  • activity_main.xml: This is where you’ll set the properties for your MapView, add a Marker, and add an InfoWindow.

Once you’ve completed all the steps in the installation guide, the four files below should include the following:

// in addition to the rest of your build.gradle contents
// you should include the following repository and dependency

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8

repositories {

dependencies {
    implementation 'com.mapbox.mapboxsdk:mapbox-android-sdk:6.7.0'
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

public class MainActivity extends AppCompatActivity {
  private MapView mapView;

  protected void onCreate(Bundle savedInstanceState) {

Mapbox.getInstance(this, getString(R.string.access_token));
mapView = (MapView) findViewById(;


  public void onStart() {

  public void onResume() {

  public void onPause() {

  public void onStop() {

  public void onLowMemory() {

  protected void onDestroy() {

  protected void onSaveInstanceState(Bundle outState) {

<?xml version="1.0" encoding="utf-8"?>

        mapbox:mapbox_cameraZoom="11" />


Configure your mapView

You can configure many of your map’s characteristics, including starting camera position and style URL, in your activity’s layout file. Replace the code you added to the activity_main.xml file in the installation flow with the following to recenter the map on Chicago, change the map style, change the pitch, and increase the zoom level:


The Mapbox Maps SDK for Android comes bundled with a handful of map styles. You can find a list of the current bundled styles with constants found in the Mapbox SDK’s Style class. In this example, you’ll use the Mapbox Light style.

See the Mapbox Maps SDK for Android documentation to view all of the XML attributes that you can set for a MapView. Customize your map to your heart’s content!

Import classes

When you’ve finished entering the above code, you will likely see some red warning text from Android Studio. This is because you haven’t yet imported some of the classes that you’re referencing in

You can automatically import these classes by pressing Alt+Enter (Option+Return on a Mac computer). Alternatively, you can manually add the following to the top of your file, anywhere above the line that reads public class MainActivity extends AppCompatActivity:

import android.os.Bundle;

import com.mapbox.mapboxsdk.Mapbox;
import com.mapbox.mapboxsdk.annotations.MarkerOptions;
import com.mapbox.mapboxsdk.geometry.LatLng;
import com.mapbox.mapboxsdk.maps.MapView;
import com.mapbox.mapboxsdk.maps.MapboxMap;
import com.mapbox.mapboxsdk.maps.OnMapReadyCallback;

Click the Run ‘app’ button icon for running the app in Android Studio(or Control+R on a Mac computer) to build your app.

Android Studio will take a few seconds to build, and if it finishes without errors, you’ll be able to test drive it in the emulated Android device that you set up earlier. Regardless of the approach you take, the result should be the same — you should see the initial map style replaced with the Mapbox Light style.

screenshot of a virtual Android device displaying a map using the Mapbox Light style

Add a marker and InfoWindow

Next, you’ll add a marker to your map. In your file, add the following code immediately after mapView.onCreate(savedInstanceState);, but still within protected void onCreate(Bundle savedInstanceState) {...});. This will wait until the map has loaded, and then add a single marker displayed at the specified coordinate.

You can also specify that an information window should be displayed when the marker is clicked. To do this for the single marker you added above, add a title and a snippet to addMarker. See the code snippet below:

mapView.getMapAsync(new OnMapReadyCallback() {
  public void onMapReady(MapboxMap mapboxMap) {
    // One way to add a marker view
    mapboxMap.addMarker(new MarkerOptions()
        .position(new LatLng(41.885,-87.679))

Rerun your application, click on the marker, and an InfoWindow should appear displaying the title and snippet.

map with marker and info window on an Android device

Next steps

You just built a small Android app with Mapbox! You can now create an Android Studio project, install the Mapbox Maps SDK for Android, and change the map style. Here are a few resources to keep you up-to-date with Mapbox:

You can also download and explore our Android demo app to see all of the simple, complex, and beautiful ways that you can use Mapbox in your Android project.