Project setup


This guide describes how you can set up your Android project to use the TomTom Maps SDK. After completing the guide you should have an empty Android project that works using Maps SDK dependencies.

Before proceeding with the project setup, ensure that your development environment meets the following requirements:

  • Android API Level: 26 (Android 8.0 "Oreo") or above.
  • NDK: version 26; other major versions may not be compatible.
  • Java: version 8 or later for sourceCompatibility and targetCompatibility.
  • Kotlin: version 1.8.0 or later.
  • OpenGL ES: 3.0 support.

For an optimal developer experience, we recommend using the following tool versions as used in our sample projects and code snippets:

  • Android Studio Jellyfish | 2023.3.1 or higher.
  • JDK version 17.
  • Android Gradle plugin version 8.4.1.
  • Gradle version 8.7.0.

Project setup

  1. Install Android Studio if you don’t already have it.

  2. Make sure to use Gradle in your project. We are no longer supporting Maven. Contact us if your project is using Maven instead of Gradle.

  3. Create a new project or open an existing one. Make sure that the minimum SDK API level is set to at least 26 (Android 8.0 "Oreo") by making the following changes in the android block of your app’s build.gradle.kts file.

    1android {
    2 defaultConfig {
    3 minSdk = 26
    4 }
  4. To prevent duplication of the file in your Android Gradle build, add the following packaging option to the android block of your app’s build.gradle.kts file.

    1android {
    2 packaging {
    3 jniLibs.pickFirsts.add("lib/**/")
    4 }

    This ensures that only one copy of is included in the build output, addressing the issue of multiple copies from different sources.

  5. To prevent potential errors during app start-up, it’s important to ensure that OpenGL ES 3.0 support is enabled in the Android Studio emulator. If your emulator supports it, navigate to Settings, choose "Renderer maximum (up to OpenGL ES 3.1)" for the "OpenGL ES API level (requires restart)" field, and then restart the emulator to apply the changes.

Configuring project dependencies

  1. Add a maven block to your settings.gradle.kts file to specify the URI for

    1dependencyResolutionManagement {
    2 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    3 repositories {
    4 google()
    5 mavenCentral()
    6 maven {
    7 url = uri("")
    8 }
    9 }
  2. Verify that everything works as expected by adding a Maps SDK dependency to the build.gradle.kts file of your application module. For example, com.tomtom.sdk.maps:map-display. Synchronize the project.

    val version = "1.5.0"
  3. Get your TomTom API key from the TomTom Developer Portal. To find out how, refer to the How to get a TomTom API key guide.

  4. Store the TomTom API key to a project property in your project file. Replace api_key_placeholder with the actual TomTom API key.

  5. Declare the tomtomApiKey variable within the build.gradle.kts file, outside of the android block.

    val tomtomApiKey: String by project
  6. Map the TomTom API key property to a custom field of the gradle BuildConfig class in the android block of your app’s build.gradle.kts file.

    1android {
    2 buildFeatures {
    3 buildConfig = true
    4 }
    5 buildTypes.configureEach {
    6 buildConfigField("String", "TOMTOM_API_KEY", "\"$tomtomApiKey\"")
    7 }

    To use the TomTom API key in your application code, it is sufficient to access the newly added BuildConfig field.

    val apiKey = BuildConfig.TOMTOM_API_KEY

Now that you’ve completed the project setup, here is what you can do next.

Learn more

After a successful project setup, you can visit the following pages with some useful suggestions on how to proceed: