Install and set up

Before installing ArcGIS Maps SDK for Kotlin, make sure your development machine meets the system requirements. A minimum Android API version is required for any target device on which your app will run. For more information, see system requirements.

We recommend installing with Gradle, which will install the needed dependencies and SDK binaries from Esri's Maven repository.

Get the API with Gradle

Perform the following set up steps in the project created for you by Android Studio's New Project wizard.

In the Project tool window, select the Android view from the drop-down menu. Open Gradle Scripts > build.gradle.kts (Project: Display_a_map). Replace the contents of the file with the following code.

build.gradle.kts (Project: Display_a_map)
Use dark colors for code blocks
// Top-level build file where you can add configuration options common to all sub-projects/modules.
plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
}

From the Android view, open Gradle Scripts > build.gradle.kts (Module :app). Replace the contents of the file with the entire expanded code below.
build.gradle.kts (Module: app)
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
    // ArcGIS Maps for Kotlin - SDK dependency
    implementation(libs.arcgis.maps.kotlin)
    // Toolkit dependencies
    implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
    implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
    implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
```
Expand
Kotlin 2.0+ requires the Compose Compiler Gradle plugin, which is referenced as alias(libs.plugins.kotlin.compose) in the plugins block at the top of the build.gradle.kts (Module :app) and declared as kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" } in the libs.versions.toml file. The version of the Compose Compiler Gradle plugin and the Kotlin Android plugin are the same.
If you are using a Kotlin version earlier than 2.0, you must verify that the Compose compiler and the Kotlin compiler versions are compatible. For details, see Compose to Kotlin Compatibility Map.
From the Android view, open Gradle Scripts > libs.versions.toml. In the [versions] section, the version number for ArcGIS Maps SDK for Kotlin must be specified. In the [libraries] section, you need library declarations for the following:
- The ArcGIS Maps SDK for Kotlin SDK.
- The ArcGIS Maps SDK for Kotlin Toolkit BOM.
- All Toolkit components that your app will be using. To display a map view or scene view, you need a declaration for the geoview-compose module, which contains the composable MapView and SceneView. To implement user authentication, you need the authentication module.
The version for the Toolkit BOM applies to all the Toolkit modules you declare.

Gradle version catalogs are the standard Android approach to declaring dependency versions. They are preferred over specifying versions numbers in the build.gradle.kts or listing version numbers in a version.gradle. In recent releases of Android Studio, the New Project Wizard generates build.gradle.kts and gradle/libs.versions.toml files that support this standard.
Gradle version catalogs can also use BOM files to specify a single version number for all artifacts in the BOM. For more details, see Using the BOM in the README of the ArcGIS Maps SDK for Kotlin Toolkit.
gradle/libs.versions.toml
Use dark colors for code blocksCopy
```
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

[versions]
arcgisMapsKotlin = "200.7.0"

[libraries]
arcgis-maps-kotlin = { group = "com.esri", name = "arcgis-maps-kotlin", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-bom = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-bom", version.ref = "arcgisMapsKotlin" }
arcgis-maps-kotlin-toolkit-geoview-compose = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-geoview-compose" }
arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }
```
Note
Don't edit your libs.version.toml by hand. Instead, expand the code below, copy the entire expanded contents, and paste it into libs.versions.toml file, replacing the original contents generated by the New Project Wizard.
gradle/libs.versions.toml
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 [versions] arcgisMapsKotlin = "200.7.0" # Version numbers added by Android Studio New Project Wizard agp = "8.7.3" kotlin = "2.0.0" coreKtx = "1.15.0" junit = "4.13.2"
Expand

From the Android view, open Gradle Scripts > settings.gradle.kts. Replace the contents of the file with the entire expanded code below.

settings.gradle.kts (Display a map)
Expand
Use dark colors for code blocks
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") }
    }
}

rootProject.name = "Tutorial"
include(":app")

Required permissions and features

Android is a permissions-separated operating system. Depending on which ArcGIS capabilities you use in your app, you may need to add permissions to your manifest. Make sure that you do not include permissions for capabilities that are not included in your app.

ArcGIS Maps SDK for Kotlin capabilities requiring permissions

Some of the capabilities of ArcGIS Maps SDK for Kotlin that you use in your app require Android permissions.

Access to the Internet. Most apps will require this.
Fine location. Access to the device's GPS will require the fine location permission. This is designated a dangerous permission in Android development.

The following code example (for the AndroidManifest.xml file) includes these permissions:

AndroidManifest.xml
Use dark colors for code blocksCopy
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Android storage and permissions

As of Android API Level 30, all apps use scoped storage for accessing the file system of the Android device. With scoped storage, an app can access (1) its own files and (2) shared files in a media store. Declaring the <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> permission is no longer supported.

Storage in Android has changed dramatically since API level 29. Consult the following links to learn more about Android storage and permissions:

Declaring OpenGL ES version

Adding a uses-feature element to the Android manifest will help the Play store make your app available to the correct type of devices.

Apps that use a MapView (2D) require at least OpenGL ES 2.x:

Use dark colors for code blocksCopy
<uses-feature android:glEsVersion="0x00020000" android:required="true" />

Apps that use a SceneView (3D) require OpenGL ES 3.x:

Use dark colors for code blocksCopy
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

Additional downloads

Additional sources of sample code and data are available to enhance your development projects. You can even download this guide as stand-alone developer documentation.

Sample code

Browse the comprehensive list of samples in the documentation or download sample code from the GitHub repository.

You can also download and interact with our live samples on your device using the sample viewer app from the Google Play Store.

ArcGIS Maps SDK for Kotlin Toolkit

The ArcGIS Maps SDK for Kotlin Toolkit contains Compose-enabled components to streamline your app development. To use the MapView and SceneView composable functions, make sure you have the following dependency in your module-level build.gradle.kts:

Use dark colors for code blocksCopy
    implementation(platform("com.esri:arcgis-maps-kotlin-toolkit-bom:200.7.0"))
    implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose")
    implementation("com.esri:arcgis-maps-kotlin-toolkit-authentication")

If you are using libs.versions.toml instead of explicit version numbers, your code will be the following.

Use dark colors for code blocksCopy
    implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
    implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
    implementation(libs.arcgis.maps.kotlin.toolkit.authentication)

For detailed instructions on what code your build.gradle.kts (Module:app) and libs.versions.toml should contain, see Get the API with Gradle above.

Key modules in the toolkit include:

The GeoView-Compose module provides Composable implementations of the MapView and SceneView classes.

The Authentication module provides a plug-and-play solution to handling authentication challenges with the ArcGIS Maps SDK for Kotlin.

The Toolkit contains several other special-purpose components, which are also Compose-enabled. For more information, see Toolkit.

Stand-alone developer documentation

You can download the developer documentation as an archive from the downloads page. The archive contains instructions to serve the documentation from a local web server so you can access it without a connection to the internet. The stand-alone documentation includes the developer guide, API reference, tutorials, and samples documentation. This documentation is designed to run on a local stand-alone computer or on an internal network and not on the public internet.

To serve the documentation locally:

Download the documentation for the SDK you want to use. The downloaded files are in a .zip archive format.
Extract the archive to a local folder. The extracted archive has two subfolders: public and install.
Open the README.md file in the install folder and follow the instructions for your chosen web server.

Supplemental data

StreetMap Premium

StreetMap Premium delivers a high-quality, multiscale cartographic map display with enriched street data. In addition, it provides accurate geocoding, optimized routing, easy to follow directions, and powerful network analysis. StreetMap Premium maps can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your apps. They are consistent across all regions of the world and are available for both online, connected scenarios and for use in offline, disconnected scenarios in the form of mobile map packages.

If you want to use StreetMap Premium data (the StreetMap Premium extension), download the demonstration data from the downloads page for development and testing. Please contact Esri Customer Service for access to a region of your choice for development and testing or to license StreetMap Premium data for deployment.

Projection Engine data

Datum transformations are used when geometries must be projected from one spatial reference to another when there is a difference in the datum that underlies the two spatial references. Datum transformations can be mathematically defined (equation-based transformations), or may rely on external supporting files (grid-based transformations). Certain Projection Engine data files must be present when you use a grid-based transformation in your app; attempting to use a transformation with missing Projection Engine files will cause an error. The API can detect whether the necessary files are available on the local file system.

If your app requires grid-based transformations, you can download supporting Projection Engine files from the downloads page. See the Spatial references topic for more information about working with coordinate systems, projections, and datum transformations.

Electronic Navigational Charts (ENC)

Electronic navigational charts (ENCs) are georeferenced vector datasets for the visualization and analysis of hydrographic and maritime information. This SDK supports ENCs that conform to the International Hydrographic Organization (IHO) S-57 standard.

If you want to work with Electronic Navigational Charts (ENC) download the hydrography directory from the downloads page.

See the Display electronic navigational charts topic for more information about working with ENC data.