Use ArcGIS basemaps

The ArcGIS Runtime SDK for Android supports a range of predefined basemaps that can be easily added to a map by using the MapOptions class. This tutorial shows you how to use the MapOptions to create a new MapView when a user selects a named basemap from an Android options menu.

Create the Basemaps project in Android Studio

ForeStart by creating a new Android application project. These steps are essentially the same as covered in the Add a map to your app tutorial. For more information about the project set up steps, refer to the Add a map to your app tutorial.

  1. In the Android Studio Welcome screen, under Quick Start, click Start a new Android Studio project.
  2. In Application name, enter Basemaps. Optionally change the Company Name and Project Location if you want to, then click Next.
    Create new project dialog window in Android Studio
  3. Leave the default Phone and Tablet option selected, in the Minimum SDK drop-down list, choose API 15: Android 4.0.3, then click Next.
  4. Click Blank Activity, then click Next.
  5. Leave the default names for the activity, layout, title, and menu resource, and click Finish.

    A new default Android application project opens, showing a default layout.

You have now successfully created an Android project containing an application module. Next you will add the Runtime Android SDK Android dependency.

Add the ArcGIS Runtime for Android AAR dependency

Here you will add the Runtime Android SDK dependency to your application module as an Android Archive (AAR) package.

  1. In the Android project view window, under Gradle Scripts, double-click build.gradle (Project: Basemaps). This opens the gradle build script for the project where you can add the Esri ArcGIS Maven repository URL as shown below:
    allprojects {
        repositories {
            // add the esri arcgis maven repo
            maven {
                url ''
  2. In the Android project view window, under Gradle Scripts, double-click build.gradle (Module: app).
  3. In the dependencies section of the script, add a new value compile '':
    dependencies {
      compile fileTree(dir: 'libs', include: ['*.jar'])
      compile '' 
  4. In the android section of the script, after defaultConfig, add the following values:
      exclude 'META-INF/LGPL2.1' 
      exclude 'META-INF/LICENSE' 
      exclude 'META-INF/NOTICE' 
  5. In the Android project view window, under manifests, double-click AndroidManifest.xml.
  6. In the AndroidManifest.xml file, add the following elements as children of the manifest element:
    <uses-feature android:glEsVersion="0x00020000"android:required="true" />
    <uses-permission android:name="android.permission.INTERNET" />
  7. In the Android Studio toolbar, click Sync Project with Gradle Files. Alternatively, when you see the Gradle files have changed since last project sync message at the top of the gradle script window, click Sync Now.

You have added a dependency to the Runtime Android SDK AAR to your app module. Next, you'll add code to your activity to add a MapView.

Set up the initial map with topo basemap

This step creates a MapView and adds the Topo basemap as its initial basemap. You will also set an initial zoom level and center the map.

  1. In the Android project view window, under app, navigate to res > layout, then double-click activity_main.xml.

    Note that depending on the type of activity chosen and the version of Android Studio, your project may contain only one layout XML file, activity_main.xml, or multiple layout files, including content_main.xml; if so, open this file instead.

  2. At the bottom-left of the window, click Text to show the XML view of the layout.
  3. Select the entire TextView XML element and replace it with a MapView element as shown below.
      mapoptions.ZoomLevel="13""33.666354, -117.903557" />

    This MapView element has mapoptions attributes that tell the MapView to display initially using a default Topo map service layer, and to center the map at a specific set of coordinates, and zoom the map to a specific level.

  4. In the Android project view window, under app, navigate to java >, then double-click MainActivity to open the activity source code file.
  5. Add the following class variable declaration to the top of the MainActivity class:
    // The MapView.
    MapView mMapView = null;

    This variable will hold a reference to the MapView you added to the layout.

  6. Android Studio will highlight in red the classes which must be imported to the class file. Place the cursor at the line with text highlighted in red and press ALT+Enter to resolve the symbol and import the class to your activity class.
    Resolve symbol error message in Android Studio

    You should resolve symbols for any similar errors you get throughout this tutorial.


    A complete list of imports is available at the end of this tutorial so you can check you have imported the classes correctly.

  7. In the OnCreate method, after the content view is set, set the reference to the MapView in the layout, and also enable wrap-around maps and the Esri logo in the map:
    // Retrieve the map and initial extent from XML layout
    mMapView = (MapView) findViewById(;
    // Enable map to wrap around date line.
  8. Override the onPause and onResume methods of the activity, and add the code below to pause and unpause the MapView when these methods are called.
    protected void onPause() {
    protected void onResume() {

You now have an app that includes a map. Next you will create the options menu items to change the basemap.

Add the basemaps options menu

Now you will define the options menu of basemaps and add code to respond when a menu option is tapped.

  1. In the Android project view window, under app, navigate to res > menu, then double-click menu_main.xml.
  2. Replace the existing item element with the following elements:
    <group android:checkableBehavior="single">
        android:title="@string/StreetMapMenu" />
        android:title="@string/TopoMenu" />
        android:title="@string/GrayMenu" />
        android:title="@string/OceanMenu" />

    This defines the basemap options in the options menu layout.

  3. In the Android project view window, under app, navigate to res > values, then double-click strings.xml.
  4. Add the following string resources:
    <!-- basemap menu items -->
    <string name="StreetMapMenu">Streets</string> 
    <string name="TopoMenu">Topographic</string> 
    <string name="GrayMenu">Gray</string> 
    <string name="OceanMenu">Oceans</string>

    These strings are used for the user interface of the options menu items for basemaps.

  5. In the Android project view window, under app, navigate to java >, then double-click MainActivity to open the activity source code file.
  6. Add the following class variable declarations to the top of the MainActivity class:
    // The basemap switching menu items.
    MenuItem mStreetsMenuItem = null;
    MenuItem mTopoMenuItem = null;
    MenuItem mGrayMenuItem = null;
    MenuItem mOceansMenuItem = null;
    // Create MapOptions for each type of basemap.
    final MapOptions mTopoBasemap = new MapOptions(MapOptions.MapType.TOPO);
    final MapOptions mStreetsBasemap = new MapOptions(MapOptions.MapType.STREETS);
    final MapOptions mGrayBasemap = new MapOptions(MapOptions.MapType.GRAY);
    final MapOptions mOceansBasemap = new MapOptions(MapOptions.MapType.OCEANS);

    These variables define:

    • The MenuItems in the options menu
    • MapOptions that will be used to set different basemaps in the MapView

  7. In the onCreateOptionsMenu method, add the following lines of code after the getMenuInflater.inflate(, menu) line, and before the return true line.
    // Get the basemap switching menu items.
    mStreetsMenuItem = menu.getItem(0);
    mTopoMenuItem = menu.getItem(1);
    mGrayMenuItem = menu.getItem(2);
    mOceansMenuItem = menu.getItem(3);
    // Also set the topo basemap menu item to be checked, as this is the default.
    This sets the variables you added previously to the menu items created when the options menu you defined in the menu layout is first shown; you will use these references in a following step. As your initial map shows the Topo map, set this to be checked.
  8. In the onOptionsItemSelected method, replace all of the method body with the following code:
    // Handle menu item selection.
    switch (item.getItemId()) {
        return true;
        return true;
        return true;
        return true;
        return super.onOptionsItemSelected(item);

    This code identifies the selected menu option and sets the appropriate MapOptions onto the MapView.

You have completed coding your basemaps app, and are now ready to test it.

Run the application

To test your app, you should either have a connected device ready for debugging, or have a set up and started an emulator. To find our more, refer to the Android documentation on Using the emulator or Using hardware devices.

  1. In the Android Studio toolbar, click Run.
  2. In the Choose Device dialog, select the device or emulator you wish to use, then click OK
  3. When the app opens on your device, it shows a topological map showing a town in California.
  4. In the action bar of the app, tap the options overflow, and select Gray.

    The map updates to show a gray basemap instead.

    Basemaps app screenshot

That's it, you have built a switch basemaps app using the MapOptions and an Android options menu. You can learn more about Android menus here.

See a completed Basemaps sample on the website. Fork the samples repo on GitHub to work with the sample.


The complete list of imports for your project should be:

import android.os.Bundle;
import;  // May vary depending Android Studio version and options chosen
import android.view.Menu;
import android.view.MenuItem;

import com.esri.core.geometry.Polygon;