Add a map to your app

This tutorial guides you through the process of creating a basic mapping app using Android Studio. You can download the complete app as a sample (see the Hello World sample). The purpose of this tutorial is to help you understand the basics of working with the ArcGIS Runtime SDK for Android in the Android Studio integrated development environment (IDE). By the end of this tutorial you will have an app that displays a map using a specific initial map extent.


You should already have a basic understanding of developing apps for the Android platform and the terminology used. See the Android Developers homepage for information about developing apps for Android.

You should also have installed the Android Studio IDE—see Install and set up for more information.

Create a new project in Android Studio

When you open Android Studio, it shows the Welcome screen. From here you can create a new Android app project.

  1. Under Quick Start, click Start a new Android Studio project.

    If you already have a project open, you can instead click File > New Project.

  2. In Application name, enter HelloWorld.

    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.
    Choose API level dialog window in Android Studio
  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. This will automatically be downloaded from the Bintray Maven central repository when you build your app.

  1. In the Android project view window, under Gradle Scripts, double-click build.gradle (Project: HelloWorld). 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).

    This opens the gradle build script for your application module. If you are unfamiliar with the Gradle build system, see Build System Overview.

  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' 

    This directive excludes duplicate files from the Android Package (APK) file created when you build your app.

  5. In the Android project view window, under manifests, double-click AndroidManifest.xml.

    This opens the Android Manifest file for your app.

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

    This indicates that your app will require permissions to perform network operations, and also requires the hardware feature OpenGL ES version 2.0. For more information about Android system permissions, see Android Permissions. For more information about THE hardware feature request, see Uses Feature Element.

  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.
    Sync now gradle message in Android Studio

You have added a dependency to the Runtime Android SDK AAR to your app module. Next, you'll add a map showing a map service to the application and set up an initial extent for that map.

Add a map

Now that you've created an app with a Runtime Android SDK AAR dependency, the next step is to add a map to the activity layout. You will specify that the map should show a worldwide street map available from However, you won't display the street map for the entire world when the map is initialized. It is often more useful for the application to initially display a map for a specific region rather than its entire extent—in this instance, a specific region of Southern California as opposed to the entire world. The following steps guide you through the process of adding a map and specifying an initial extent for the application:

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

    This opens the Preview view of the central content of the main activity layout. 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; if so, open this file instead.

  2. At the bottom-left of the window, click Text to show the XML view of the layout.

    By default, there are two tags in the layout XML file.

    • The first is the Android relative layout. This is a view which can show other views inside itself. It arranges its children views relative to each other. For more information on this layout template, see the Relative Layout documentation provided by Google. For a detailed explanation of the Android view hierarchy, see the User Interface documentation.
    • The second tag is the TextView tag, considered the child view in this example. This tag is used to add text to the application, in this case "Hello World, HelloWorld!".

  3. Select the entire TextView XML element and replace it with a MapView element as shown below.

    This MapView element has mapoptions attributes that tell the MapView how to display. These options will use a default Streets map service layer, center the map at a specific set of coordinates, and zoom the map to a specific level.

      mapoptions.MapType="Streets""34.056215, -117.195668"

    Your XML layout should now look like that shown below.

    Edited XML layout in Android Studio

    You are now ready to build the application.

  4. Click Make Project in the Android Studio toolbar, or click Build > Make Project.

    At the bottom of Android Studio you should see a message Gradle build finished. You can click the Gradle Console, at the bottom right of Android Studio, to see messages from the Gradle build process; this should indicate BUILD SUCCESSFUL.

You have now completed the steps to add a Runtime Android SDK map to your new Android app. For a deeper understanding of the declarative approach to user interface (UI) design, see Declaring Layout.

Your application is now ready for testing.

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 street map centered on Redlands, California. You can double-tap the map to zoom in.

When you create a new project, Android Studio automatically creates a run configuration to launch the app on your device. You'll see something similar to the following screen shot:

Hello World app screenshot showing map

That's it, you have completed your first ArcGIS Runtime SDK for Android app. A downloadable Hello World sample app module is available as part of the Runtime Android SDK samples hosted on GitHub. You can find out more about the Hello World sample on the website, and then fork the GitHub repo.