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.
- A development and deployment environment that meets the system requirements.
- 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.
-
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)
- Name:
-
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:
build.gradle (Project: Display_a_map)Use dark colors for code blocks Change line Change line Change line Change line Change line Change line Change line Change line Change line Change line // 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 }
-
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 Change line Change line Change line Change line Change line Change line Change line Change line Change line Change line apply plugin: 'com.android.application' apply plugin: 'org.jetbrains.kotlin.android' android { compileSdk 33 defaultConfig { applicationId "com.example.app" minSdkVersion 26 targetSdk 33
-
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 Change line Change line Change line Change line Change line Change line Change line Change line Change line Change line pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } } dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
-
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 internet access.
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.
AndroidManifest.xmlUse dark colors for code blocks Add line. <manifest xmlns:android="http://schemas.android.com/apk/res/android"> <uses-permission android:name="android.permission.INTERNET"/>
Add import statements
Open app > java > com.example.app MainActivity.kt, and add import statements to reference the API.
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.
-
In app > res > layout > activity_main.xml, replace the entire
Text
element with aView 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
Map
element creates an instance of theView MapView
class from the ArcGIS Maps SDK for Kotlin.In your main activity source code, you can access that
MapView
instance using an implicit property, which is declared in the value of theandroid:
attribute. In this case, the property will be namedid map
.View activity_main.xmlUse dark colors for code blocks Change line Change line Change line Change line <?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>
-
In MainActivity.kt, create a lazy property named
activity
. Use the Android classMain Binding Data
to set the content view of the main activity to the given layout.Binding Util MainActivity.ktUse dark colors for code blocks class MainActivity : AppCompatActivity() { private val activityMainBinding: ActivityMainBinding by lazy { DataBindingUtil.setContentView(this, R.layout.activity_main) }
-
Create a lazy property named
map
and bind it to theView map
specified in activity_main.xml.View MainActivity.ktUse dark colors for code blocks class MainActivity : AppCompatActivity() { private val activityMainBinding: ActivityMainBinding by lazy { DataBindingUtil.setContentView(this, R.layout.activity_main) } 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.
-
In MainActivity.kt, add a new
setup
method in yourMap() Main
class. In the method, create anActivity ArcGISMap
.Configure
ArcGISMap
using a specific basemap style namedBasemapStyle.ArcGISTopographic
.MainActivity.ktUse dark colors for code blocks private fun setupMap() { val map = ArcGISMap(BasemapStyle.ArcGISTopographic) }
-
Set the
map
property ofmap
to the newView ArcGISMap
. Then create aViewpoint
and add it to themap
.View MainActivity.ktUse dark colors for code blocks 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)) }
-
In the
o
method, look for the coden Create() set
and, if found, delete it.Content View(R.layout.activity_ main) If you used Android Studio's New Project wizard, it may have written
set
in theContent View(R.layout.activity_ main) o
lifecycle function. You should delete that code. In its place, you will use the lazy propertyn Create() activity
, which you declared in an earlier step.Main Binding -
In the
o
method, calln Create() lifecycle.add
and pass the map view. Then callObserver() setup
, the function you defined in the previous steps.Map() MainActivity.ktUse dark colors for code blocks Add line. Add line. override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) lifecycle.addObserver(mapView) setupMap() }
Set your API key
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
set
method, where you will set theA p i Key() ArcGISEnvironment.apiKey
property by callingApiKey.create()
and passing your API key as a string. Don't forget the quotes.MainActivity.ktUse dark colors for code blocks Add line. Add line. Add line. Add line. Add line. Add line. Add line. 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") }
-
Call
set
in theA p i Key() o
lifecycle method, before then Create() setup
call.Map() MainActivity.ktUse dark colors for code blocks Add line. override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) lifecycle.addObserver(mapView) setApiKey() setupMap() }
Add error message (optional)
-
Create the
show
function, which displays the error in a Toast in the app UI and logs the error in Android Studio (visible in the Logcat tab).Error() This initial tutorial (Display a map) is quite simple and does not call
show
. 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.Error() MainActivity.ktUse dark colors for code blocks Add line. Add line. Add line. Add line. private fun showError(message: String) { Toast.makeText(applicationContext, message, Toast.LENGTH_LONG).show() Log.e(localClassName, message) }
Run your app
-
Click Run > Run > app to run the app.
In Android Studio, you have two choices for running your app: an actual Android device or the Android Emulator.
Android device
Connect your computer to your Android device, using USB or Wi-Fi. For more details, see How to connect your Android device.
Android Emulator
Create an AVD (Android Virtual Device) to run in the Android Emulator. For details, see Run apps on the Android Emulator.
Selecting a device
When you build and run an app in Android Studio, you must first select a device. From the Android Studio toolbar, you can access the drop-down list of your currently available devices, both virtual and physical.
.
If you cannot access the list on the toolbar, click Tools > Device Manager.
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: