Display a map

Learn how to create and display a map with a basemap layer.

display a map

A map contains layers of geographic data. A map contains a basemap layer and, optionally, one or more data layers. You can display a specific area of a map by using a map view and setting the location and zoom level.

In this tutorial, you create and display a map of the Santa Monica Mountains in California using the topographic basemap layer.

The map and code will be used as the starting point for other 2D tutorials.

Prerequisites

Before starting this tutorial:

  1. You need an ArcGIS Location Platform or ArcGIS Online account.

  2. Confirm that your system meets the system requirements.

  3. An IDE for Android development in Kotlin.

Steps

Create a new Android Studio project

Use Android Studio to create an app and configure it to reference the API.

  1. Open Android Studio.

    • In the menu bar, click File > New > New Project....
    • In the Create New Project window, make sure Phone and Tablet tab is selected, and then select Empty Activity. Click Next.
    • In the Configure your project window, set the following configuration options:
      • Name: Display a map.
      • Package name: Change to com.example.app. Or change to match your organization.
      • Save location: Set to a new folder.
      • Language: Kotlin
      • Minimum SDK: API 23: Android 6.0 (Marshmallow)
  2. In the Project tool window, make sure that your current view is Android. These tutorial instructions refer to that view.

  3. From the Project tool window, open Gradle Scripts > build.gradle (Project: Display_a_map). Replace the contents of the file with the following code:

    build.gradle (Project: Display_a_map)
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 11
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    // Top-level build file where you can add configuration options common to all sub-projects/modules.
    
    plugins {
        id 'com.android.application' version '7.2.1' apply false
        id 'com.android.library' version '7.2.1' apply false
        id 'org.jetbrains.kotlin.android' version '1.7.0' apply false
    }
    
    task clean(type: Delete) {
        delete rootProject.buildDir
    }
  4. From the Project tool window, open Gradle Scripts > build.gradle (Module: Display_a_map.app). Replace the contents of the file with the following code:

    build.gradle (Module: app)
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    plugins {
        id 'com.android.application'
        id 'org.jetbrains.kotlin.android'
    }
    
    android {
        compileSdkVersion 32
    
        defaultConfig {
            applicationId "com.example.app"
            minSdkVersion 23
            targetSdkVersion 32
            versionCode 1
            versionName "1.0"
        }
    
        buildTypes {
            release {
                minifyEnabled false
                proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            }
        }
    
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
        }
    
        kotlinOptions {
            jvmTarget = JavaVersion.VERSION_1_8.toString()
        }
    
        buildFeatures {
            viewBinding true
        }
    
        packagingOptions {
            exclude 'META-INF/DEPENDENCIES'
        }
    
    }
    
    dependencies {
        implementation fileTree(dir: "libs", include: ["*.jar"])
        implementation 'androidx.appcompat:appcompat:1.4.2'
        implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
        implementation 'androidx.multidex:multidex:2.0.1'
        implementation 'com.google.android.material:material:1.6.1'
    
        implementation 'com.esri.arcgisruntime:arcgis-android:100.15.0'
    }
  5. From the Project tool window, open Gradle Scripts > settings.gradle. Replace the contents of the file with the following code:

    settings.gradle (Display a map)
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    import org.gradle.api.initialization.resolve.RepositoriesMode
    
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    }
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
    
            maven {
                url 'https://esri.jfrog.io/artifactory/arcgis'
            }
        }
    }
    
    rootProject.name = "Display a map"
    
    include ':app'
  6. Sync the Gradle changes. Click the Sync now prompt or click the refresh icon (Sync Project with Gradle Files) in the toolbar. This may take several minutes.

  7. From the Project tool window, open app > manifests > AndroidManifest.xml. Update the Android manifest to allow network access, and also to indicate the app uses OpenGL 2.0 or above.

    AndroidManifest.xml
    Expand
    Use dark colors for code blocks
    3 4 5 6 7 8 9 10
    Add line.Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.example.app">
    
        <uses-permission android:name="android.permission.INTERNET" />
        <uses-feature
            android:glEsVersion="0x00020000"
            android:required="true" />
    
    Expand

Add import statements

Open app > java > com.example.app MainActivity.kt, and add import statements to reference the ArcGIS Runtime API.

MainActivity.kt
Use dark colors for code blocks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
package com.example.app

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

import com.esri.arcgisruntime.ArcGISRuntimeEnvironment
import com.esri.arcgisruntime.mapping.ArcGISMap
import com.esri.arcgisruntime.mapping.BasemapStyle
import com.esri.arcgisruntime.mapping.Viewpoint
import com.esri.arcgisruntime.mapping.view.MapView

import com.example.app.databinding.ActivityMainBinding

class MainActivity : AppCompatActivity() {

Add a UI for the map view

A map view is a UI component that displays a map. It also handles user interactions with the map, including navigating with touch gestures. Use XML to add a map view to the UI and make it available to the main activity source code.

  1. In app > res > layout > activity_main.xml, replace the entire TextView element with a MapView element.

    activity_main.xml
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    <?xml version="1.0" encoding="utf-8"?>
    <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto"
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".MainActivity">
    
        <com.esri.arcgisruntime.mapping.view.MapView
            android:id="@+id/mapView"
            android:layout_width="0dp"
            android:layout_height="0dp"
            app:layout_constraintBottom_toBottomOf="parent"
            app:layout_constraintEnd_toEndOf="parent"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintTop_toTopOf="parent" />
    
    </androidx.constraintlayout.widget.ConstraintLayout>
  2. In MainActivity.kt, create a read-only local variable named activityMainBinding referencing the generated Android class ActivityMainBinding.

    MainActivity.kt
    Use dark colors for code blocks
    30 31 32 33 34 35
    Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    class MainActivity : AppCompatActivity() {
    
        private val activityMainBinding by lazy {
            ActivityMainBinding.inflate(layoutInflater)
        }
    
    
  3. Create a read-only variable named mapView and bind it to the mapView created in activity_main.xml.

    MainActivity.kt
    Use dark colors for code blocks
    30 31 32 33 34 35 36 37 38
    Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    class MainActivity : AppCompatActivity() {
    
        private val activityMainBinding by lazy {
            ActivityMainBinding.inflate(layoutInflater)
        }
    
        private val mapView: MapView by lazy {
            activityMainBinding.mapView
        }
    

Add a map

Use the map view to display a map centered on the Santa Monica Mountains in California. The map will contain a topographic basemap layer.

  1. In MainActivity.kt, add a new setupMap() method in your MainActivity class. In the method, create an ArcGISMap.

    MainActivity.kt
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        // set up your map here. You will call this method from onCreate()
        private fun setupMap() {
    
            // create a map with the BasemapStyle streets
            val map = ArcGISMap(BasemapStyle.ARCGIS_TOPOGRAPHIC)
    
        }
    
  2. Set the map property of mapView to the new ArcGISMap. Then create a ViewPoint and add it to the mapView.

    MainActivity.kt
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        // set up your map here. You will call this method from onCreate()
        private fun setupMap() {
    
            // create a map with the BasemapStyle streets
            val map = ArcGISMap(BasemapStyle.ARCGIS_TOPOGRAPHIC)
    
            // set the map to be displayed in the layout's MapView
            mapView.map = map
    
            // set the viewpoint, Viewpoint(latitude, longitude, scale)
            mapView.setViewpoint(Viewpoint(34.0270, -118.8050, 72000.0))
    
        }
    
  3. In the onCreate() method, replace the Android Studio default call setContentView(R.layout.activity_main) with setContentView(activityMainBinding.root). Then call setupMap().

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    40 41 42 43 44 45 46 47
    Change lineAdd line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
    
            setContentView(activityMainBinding.root)
    
            setupMap()
    
        }
    
    Expand
  4. Override the onPause(), onResume(), and onDestroy() methods of the MainActivity class.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    49 50 51 52 53 54 55 56 57 58 59 60 61 62
    Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        override fun onPause() {
            mapView.pause()
            super.onPause()
        }
    
        override fun onResume() {
            super.onResume()
            mapView.resume()
        }
    
        override fun onDestroy() {
            mapView.dispose()
            super.onDestroy()
        }
    
    Expand

Get an access token

You need an access token to use the location services used in this tutorial.

  1. Go to the Create an API key tutorial to obtain an access token.

  2. Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service.

  3. Copy the access token as it will be used in the next step.

To learn more about other ways to get an access token, go to Types of authentication.

Set your API key

  1. Create the setApiKeyForApp() method, in which you set the apiKey property on the ArcGISRuntimeEnvironment using the access token. Paste your access token inside the quotes, replacing YOUR_ACCESS_TOKEN.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    59 60 61 62 63 64 65 66 67 68
    Add line.Add line.Add line.Add line.Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        override fun onDestroy() {
            mapView.dispose()
            super.onDestroy()
        }
    
        private fun setApiKeyForApp(){
    
            ArcGISRuntimeEnvironment.setApiKey("YOUR_ACCESS_TOKEN")
    
        }
    
    Expand
  2. Call setApiKeyForApp() in the onCreate() lifecycle method.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    40 41 42 43 44 45 46 47 48 49
    Add line.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
    
            setContentView(activityMainBinding.root)
    
            setApiKeyForApp()
    
            setupMap()
    
        }
    
    Expand
  3. Click Run > Run > app to run the app.

You should see a map with the topographic basemap layer centered on the Santa Monica Mountains in California. Pinch, drag, and double-tap the map view to explore the map.

What's next?

Learn how to use additional API features, ArcGIS location services, and ArcGIS tools in these tutorials:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.