Get started

There are a number of ways to get started to develop with the ArcGIS Maps SDK for Kotlin. If you are new, follow the steps below to get started with Kotlin and Android Studio.

To use the ArcGIS Maps SDK for Kotlin to access content, services, or an organization, you need an ArcGIS Developer account, ArcGIS Online account, or ArcGIS Enterprise account. The type of account, user type, and role you need depends on the resource you need to access and the operations you wish to undertake.

If you do not have an account, select one of the options below:

Get started for free with ArcGIS Platform

Get a free trial for ArcGIS Online

2. Get the SDK and dependencies

To use the ArcGIS Maps SDK for Kotlin you need to:

Install an Android IDE with Gradle integrated.

The official IDE for Android app development is Android Studio, which can be installed as follows.

Check the Android Studio system requirements for your operating system, architecture, and version.
Download Android Studio.

You should install the latest stable version of Android Studio.
Run the installation file, following instructions in the Android Studio Setup wizard.

Install a JDK for Gradle

Installing Android Studio automatically installs an embedded version of the JDK, normally in a subdirectory named jbr. Gradle, however, uses its own JVM when starting the Gradle daemon. If these two versions of the JVM are not the same, Gradle may spawn extra deamons, which can slow down builds.

You should manually set the JDK that Gradle uses and make sure the embedded JDK and the Gradle JDK are the same version.

On the file system of your development machine, go to the jbr directory underneath the Android Studio installation. Open the release file and find the value of the JAVA_VERSION environment variable.
In Android Studio, access the Settings (Windows) or Preferences (macOS) dialog from the File menu.
Click Build, Execution, Deployment > Build Tools > Gradle.
In the Gradle JDK field, select a JDK that has the same version as the embedded JDK.

Get the ArcGIS Maps SDK for Kotlin and dependencies

Expand the accordion below: Gradle build script. This is the module-level build script used in the Display a map tutorial.
Copy the script into the module-level build.gradle.kts (normally, app/build.gradle.kts) file for your project.
Reload the build script and build or run your project to download and unpack the API, its resources, and all dependencies.

For additional considerations, go to Install and set up.

Use dark colors for code blocksCopy

plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
}

android {
    compileSdk = 34

    defaultConfig {
        applicationId = "com.example.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        compose = true
        buildConfig = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.3"
    }

    kotlinOptions {
        jvmTarget = "17"
    }

    packaging {
        resources {
            excludes += "/META-INF/DEPENDENCIES"
        }
    }

    namespace = "com.example.app"
}

dependencies {
    implementation("androidx.core:core-ktx:1.12.0")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
    implementation("androidx.activity:activity-compose:1.8.2")
    // Jetpack Compose Bill of Materials
    implementation(platform("androidx.compose:compose-bom:2023.10.01"))
    // Jetpack Compose dependencies
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    // ArcGIS Map Kotlin SDK dependencies
    implementation("com.esri:arcgis-maps-kotlin:200.4.0")
    // Toolkit dependencies
    implementation(platform("com.esri:arcgis-maps-kotlin-toolkit-bom:200.4.0"))
    implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose")
}

The first time you build a project, the Gradle build script will transfer the ArcGIS Maps API for Kotlin and its resources into a .arcgis folder located in the user's home directory.

3. Get an access token

To access secure ArcGIS services and resources, you need to use an access token. The easiest way to get started is to create an API key. Learn more about access tokens and authentication in Security and authentication.

Get an API key

Implement OAuth 2.0

4. Create your first mapping application

Follow the step-by-step instructions in the Display a map tutorial to create your first mapping application. The following code shows how you can create and display a map.

Expand
Use dark colors for code blocksCopy
@Composable
fun MainScreen() {

    val map = remember {
        createMap()
    }

    Scaffold(
        topBar = { TopAppBar(title = { Text(text = stringResource(id = R.string.app_name)) }) }
    ) {

        MapView(
            modifier = Modifier.fillMaxSize().padding(it),
            arcGISMap = map
        )

    }

}

fun createMap(): ArcGISMap {

    return ArcGISMap(BasemapStyle.ArcGISTopographic).apply {

        initialViewpoint = Viewpoint(
            latitude = 34.0270,
            longitude = -118.8050,

            scale = 72000.0

        )

    }

}

Once you are done building your application, make sure to license it before deploying to production. For more information, see License and deployment topic for details.