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

The following are required for this tutorial:

  1. An ArcGIS account to access API keys. If you don't have an account, sign up for free.
  2. A development and deployment environment that 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 26: Android 8.0 (O)
  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
    Change lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    // Top-level build file where you can add configuration options common to all sub-projects/modules.
    plugins {
        id 'com.android.application' version '8.1.1' apply false
        id 'com.android.library' version '8.1.1' apply false
        id 'org.jetbrains.kotlin.android' version '1.9.10' apply false
    }
    
    tasks.register('clean', Delete) {
        delete rootProject.buildDir
    }
  4. From the Project tool window, open Gradle Scripts > build.gradle (Module: Display_a_map.app). Expand the code block below, and replace the contents of the file with the expanded code:

    build.gradle (Module: app)
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10
    Change 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
    apply plugin: 'com.android.application'
    apply plugin: 'org.jetbrains.kotlin.android'
    
    android {
        compileSdk 33
    
        defaultConfig {
            applicationId "com.example.app"
            minSdkVersion 26
            targetSdk 33
    
    Expand
  5. From the Project tool window, open Gradle Scripts > settings.gradle. Expand the code block below, and replace the contents of the file with the expanded code:

    settings.gradle (Display a map)
    Use dark colors for code blocks
    1 2 3 4 5 6 7 8 9 10 10 10 10 10 10 10 10 10 10 10 10
    Change 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
    pluginManagement {
        repositories {
            gradlePluginPortal()
            google()
            mavenCentral()
        }
    }
    
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    
    Expand
  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 internet access.

    AndroidManifest.xml
    Expand
    Use dark colors for code blocks
    2 2 3 4 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5 5
    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
    <manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
        <uses-permission android:name="android.permission.INTERNET"/>
    
    Expand

Add import statements

Open app > java > com.example.app MainActivity.kt, and add import statements to reference the 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
package com.example.app

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.util.Log
import android.widget.Toast
import androidx.databinding.DataBindingUtil
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.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
    Change lineChange lineChange lineChange line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    <?xml version="1.0" encoding="utf-8"?>
    <layout xmlns:android="http://schemas.android.com/apk/res/android">
    
        <androidx.constraintlayout.widget.ConstraintLayout xmlns:tools="http://schemas.android.com/tools"
            android:layout_width="match_parent"
            android:layout_height="match_parent"
            tools:context=".MainActivity">
    
            <com.arcgismaps.mapping.view.MapView
                android:id="@+id/mapView"
                android:layout_width="match_parent"
                android:layout_height="match_parent" />
    
        </androidx.constraintlayout.widget.ConstraintLayout>
    </layout>
  2. In MainActivity.kt, create a lazy property named activityMainBinding. Use the Android class DataBindingUtil to set the content view of the main activity to the given layout.

    MainActivity.kt
    Expand
    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
    class MainActivity : AppCompatActivity() {
    
        private val activityMainBinding: ActivityMainBinding by lazy {
            DataBindingUtil.setContentView(this, R.layout.activity_main)
        }
    
    
    Expand
  3. Create a lazy property named mapView and bind it to the mapView specified in activity_main.xml.

    MainActivity.kt
    Expand
    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
    class MainActivity : AppCompatActivity() {
    
        private val activityMainBinding: ActivityMainBinding by lazy {
            DataBindingUtil.setContentView(this, R.layout.activity_main)
        }
    
        private val mapView: MapView by lazy {
            activityMainBinding.mapView
        }
    
    Expand

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
    Expand
    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
        private fun setupMap() {
    
            val map = ArcGISMap(BasemapStyle.ArcGISTopographic)
    
        }
    
    Expand
  2. Set the map property of mapView to the new ArcGISMap. Then create a Viewpoint and add it to the mapView.

    MainActivity.kt
    Expand
    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
        private fun setupMap() {
    
            val map = ArcGISMap(BasemapStyle.ArcGISTopographic)
    
            // set the map to be displayed in the layout's MapView
            mapView.map = map
    
            mapView.setViewpoint(Viewpoint(34.0270, -118.8050, 72000.0))
    
        }
    
    Expand
  3. In the onCreate() method, look for the code setContentView(R.layout.activity_main) and, if found, delete it.

  4. In the onCreate() method, call lifecycle.addObserver() and pass the map view. Then call setupMap(), the function you defined in the previous steps.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 43 44 45 46 47 47 47 48 49 50 51 51 51 51 51 51 51 51 51 51 51 51 51 50 49 48 47 46 45 44 43 42 41 40 39 38 38
    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
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
    
            lifecycle.addObserver(mapView)
    
            setupMap()
    
    
        }
    
    Expand

Set your API key

An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.

  1. Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.

  2. Create the setApiKey() method, where you will set the ArcGISEnvironment.apiKey​ property by calling ApiKey.create() and passing your API key as a string. Don't forget the quotes.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 65 64 63 63 63 63 63 63 63 63 63 63 63 63 63 63 63 63 63 64 65 66 67 68 69 70 70 69 68 67 66 65 65
    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
        private fun setApiKey() {
            // It is not best practice to store API keys in source code. We have you insert one here
            // to streamline this tutorial.
    
            ArcGISEnvironment.apiKey = ApiKey.create("YOUR_API_KEY")
    
        }
    
    Expand
  3. Call setApiKey() in the onCreate() lifecycle method, before the setupMap() call.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 43 44 45 46 47 48 49 50 51 52 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 53 52 51 50 49 48 48
    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
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
    
            lifecycle.addObserver(mapView)
    
            setApiKey()
    
            setupMap()
    
    
        }
    
    Expand

Add error message (optional)

  1. Create the showError() function, which displays the error in a Toast in the app UI and logs the error in Android Studio (visible in the Logcat tab).

    This initial tutorial (Display a map) is quite simple and does not call showError(). Many of the subsequent tutorials are based on Display a map and will need to call this function. Define it now for convenient use in those tutorials.

    MainActivity.kt
    Expand
    Use dark colors for code blocks
    73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 73 74 75 76 77 77 77
    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
        private fun showError(message: String) {
            Toast.makeText(applicationContext, message, Toast.LENGTH_LONG).show()
            Log.e(localClassName, message)
        }
    
    Expand

Run your app

  1. 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.