Learn how to create and display a map with a basemap layer.
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:
An ArcGIS account to access API keys. If you don't have an account, sign up for free.
Use Android Studio to create an app and configure it to reference the API.
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.
Gradle is the default build tool in Android Studio. If you are unable to use Gradle, see Getting the API Manually.
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)
In the Project tool window, make sure that your current view is Android. These tutorial instructions refer to that view.
If your view name is something other than Android (such as Project or Packages), click on the leftmost control in the title bar of the Project tool window, and select Android from the list.
From the Project tool window, open Gradle Scripts > build.gradle (Project: Display_a_map). Replace the contents of the file with the following code:
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
}
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:
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.
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.
Insert these new elements within the manifest element. Do not alter or remove any other statements.
Depending on what ArcGIS functionality you add in future tutorials, it is likely you will need to add additional permissions to your manifest.
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.
In app > res > layout > activity_main.xml, replace the entire TextView element with a MapView element.
If you do not see the XML code, select the Code tab to switch out of design mode and display the XML code in the editor.
Your MapView element creates an instance of the MapView class from the ArcGIS Runtime API for Android.
In your main activity source code, you can access that MapView instance using an implicit property, which is declared in the value of the android:id attribute. In this case, the property will be named mapView.
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
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
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
87
88
89
// set up your map here. You will call this method from onCreate()privatefunsetupMap() {
// create a map with the BasemapStyle streetsval 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))
}
In the onCreate() method, replace the Android Studio default call setContentView(R.layout.activity_main) with setContentView(activityMainBinding.root). Then call setupMap().
Creating a new Android Studio project for Kotlin or Java automatically uses setContentView(R.layout.activity_main). You can run the map view from the activity_main layout, but this requires a separate extension in the gradle script.
The MapView needs to know when your app goes to the background or is restored from background in order to properly manage the view. When the view is no longer needed, its resources should be released with a call to dispose.
You can place these methods anywhere inside your MainActivity class definition.
An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.
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.
Create the setApiKeyForApp() method, in which you set the apiKey property on the ArcGISRuntimeEnvironment using the API Key. Paste your API key inside the quotes, replacing YOUR_API_KEY.
The Android Emulator should display and run your app in the Android Virtual Devcie (AVD) selected in the Android Studio toolbar:
If your app builds but no AVD displays, you need to add one. Click Tools > AVD Manager > Create Virtual Device...
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.