// Create a new MapView passing Context
MapView mapView = new MapView(this);
mapView.setTileSource(new MapboxTileLayer("username.mapid"));

An open source toolkit for building native map applications on Android.

Mapbox Android SDK0.7.4

Getting Started

This guide will take you through the process of adding a map to your Android app. It assumes you have a Java IDE (like Eclipse or IntelliJ IDEA) with the Android SDK installed, and an app project open.

Required permissions

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.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

If your project needs to access location services, it'll also need the following permissions too:

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

The MapView

The MapView class is the key component of our library. It behaves like any other ViewGroup and its behavior can be changed statically with an XML layout file, or programmatically during runtime.

XML layout

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

mapbox:mapid="Your MapBox mapid"
mapbox:accessToken="Your Mapbox Access Token"/>

And then you can call it programmatically with


On runtime

On runtime you can create a new MapView by specifying the context of the application and a valid MapBox mapid, a TileJSON file or a zxy image template.

MapView mapView = new MapView(context);
mapView.setAccessToken("Your Mapbox Access Token");
mapView.setTileSource(new MapboxTileLayer("mapbox.streets"));
And set it as the current view like this:


Anything visual that is displayed over the map, maintaining its geographical position, we call it an Overlay. To access a MapView's overlays at any point during runtime, use:



Adding a marker with the default styling is as simple as calling this for every marker you want to add:

Marker marker = new Marker(mapView, title, description, LatLng)

Location overlay

The location of the user can be displayed on the view using UserLocationOverlay

UserLocationOverlay myLocationOverlay = new UserLocationOverlay(this, mapView);


Paths are treated as any other Overlay, and are drawn like this:

PathOverlay line = new PathOverlay(Color.RED, 3);
line.addPoint(new LatLng(51.2, 0.1));
line.addPoint(new LatLng(51.7, 0.3));

Drawing anything into the map

To add anything with a higher degree of customization you can declare your own Overlay subclass and define what to draw by overriding the draw method. It will give you a Canvas object for you to add anything to it:

class AnyOverlay extends Overlay{
    protected void draw(Canvas canvas, MapView mapView, boolean shadow) {
        //do anything with the Canvas object

Screen rotation

By default, every time the screen is rotated, Android will call onCreate and return all states in the app to their inital values. This includes current zoom level and position of the MapView. The simplest way to avoid this is adding this line to your AndroidManifest.xml, inside :


Alternatively you can override the methods onSaveInstanceState() and onRestoreInstanceState() to have broader control of the saved states in the app. See this StackOverflow question for more information on these methods.

Including SDK JavaDoc

JavaDocs are automatically generated and distributed with each official and SNAPSHOT release and can be downloaded for local viewing and / or integration with an IDE.

Generating SDK Documentation (aka JavaDoc)

cd <PROJECT_HOME>/MapboxAndroidSDK/
../gradlew clean assembleRelease generatereleaseJavadoc
cd build/docs/javadoc
open index.html