Get Started with the Maps SDK for Android
This guide describes the steps to install the most recent version of the Mapbox Maps SDK for Android, configure your Android app to use the SDK, and initialize a map.
Prerequisites
- A Mapbox account: Sign up or log into a free account on Mapbox.
- Android Studio: This guide includes details specific to the latest version of Android Studio.
- Gradle: Make sure you have Gradle installed.
Part 1: Configure your credentials
Before starting to develop your application with the Maps SDK, you'll need to create and configure your credentials.
Step 1: Configure your public token
Your app must have a public access token configured to associate its usage of Mapbox resources with your account.
Follow these steps to add a public access token from your Mapbox account as an Android string resource.
- Open your project folder or create a new project in Android Studio.
- If creating a new project, we recommend using the
Empty Activity
project type.
- Locate the resource folder:
- In the project explorer, open your resource folder located at
app/res/values
.
- Create a new resource file:
- Left click on the resource folder
- Select
New
>Values Resource File
- Name the file
mapbox_access_token.xml
- Click the
Ok
button.
- In the new file, copy and paste the code snippet below.
- Make sure you are signed in to docs.mapbox.com. This will insert your default public token into the code snippet (a long string that starts with
pk.
). - If you are not signed in, you will need to replace the placeholder
YOUR_MAPBOX_ACCESS_TOKEN
with a token from your account's tokens page.
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools">
<string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">YOUR_MAPBOX_ACCESS_TOKEN</string>
</resources>
Your public access token is now available for use in your Android project. You will access it via the string resource you created in your implementation code.
Advanced Topics: Best Practices, Rotating Tokens & Adding Tokens at Runtime
Learn how to keep access tokens private in mobile apps.
Adding Tokens at Runtime
You can also implement tokens at runtime, but this requires you to have a separate server to store your tokens. This is helpful if you want to rotate your tokens or add additional security by storing your tokens outside of the APK, but is a much more complex method of implementation.
If you do choose to follow this method, we recommend calling MapboxOptions.accessToken = YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN
before inflating the MapView
, otherwise the app will crash.
Rotating Tokens
For more information on access token rotation, consult the Access Tokens Information page.
Step 2: (Optional) Configure permissions
If you need to access the user's location to show it on the map, follow the steps below. If you do not need to access the user's location, skip to Part 2: Add the dependency.
- Open the Android Manifest.
- In the project explorer, go to
app > manifests > AndroidManifest.mxl
.
- In the project explorer, go to
- Determine the level of location access you need.
- If you only need general user location access, copy the first line of code below - the
ACCESS_COARSE_LOCATION
permission. - If you also need access to more precise location data, copy the entire code snippet, including the
ACCESS_FINE_LOCATION
permission. TheACCESS_FINE_LOCATION
will not work without also requestingACCESS_COARSE_LOCATION
access.
- If you only need general user location access, copy the first line of code below - the
- Add the permissions you copied to the Android Manifest.
- This code should be added to the top of
AndroidManifest.xml
, below the opening manifest tag and above the opening<application>
tag.
- This code should be added to the top of
You can check whether the user has granted location permission and request permissions if the user hasn't granted them yet using the PermissionsManager
.
Part 2: Add the dependency
Step 1: Add the Mapbox Maven Repository
Now that you have your credentials, add the dependency to your project.
Mapbox provides the Maps SDK via Maven.
To add the Mapbox Maps SDK as a dependency, you will need to configure your build to download the Maps SDK from Mapbox maven repository directly by following these steps:
- In the project explorer, go to Gradle Scripts >
settings.gradle
file under theGradle Scripts
section and open thesettings.gradle.kts
file. - Add a new
maven {...}
definition inside thedependencyResolutionManagement.repositories
. The hidden sections of the snippet below mimic thesettings.gradle.kts
file so you can see exactly where to place the snippet below:
Make sure you configure the Mapbox maven repository inside dependencyResolutionManagement
and not inside pluginManagement
.
Step 2: Add Maps SDK Dependencies
- Open up your module-level (for example
app
>GradleScripts
>build.gradle.kts
) Gradle configuration file and make sure that your project'sminSdk
is 21 or higher:
android {
...
defaultConfig {
minSdk 21
...
}
}
android {
...
defaultConfig {
minSdk = 21
...
}
}
- Add the Mapbox SDK for Android dependency in the same module-level (for example
app
>GradleScripts
>build.gradle.kts
) Gradle configuration file and add the following line to the dependencies section:
dependencies {
...
implementation 'com.mapbox.maps:android:11.10.0'
...
}
dependencies {
...
implementation("com.mapbox.maps:android:11.10.0")
...
}
Starting from v11.8.0, the Mapbox Maps SDK for Android brings a transitive dependency on Google Play Services, from which the SDK gets an HTTP client that supports HTTP/3.
The Google Play Services dependency can be removed, and then the SDK will work without support for HTTP/3. For details about how to manage this dependency, follow the instructions in our Removing Google Play guide.
- (Optional) If you are using Jetpack Compose to build your app, you will need to add the following to your
app/build.gradle.kts
configuration file:
- Add
compose = true
to the build features section if it's not already there as seen in the code below. - Add the Mapbox SDK Jetpack Compose Extension to dependencies section as seen in the code below..
android {
buildFeatures {
compose true
}
composeOptions {
kotlinCompilerExtensionVersion = "1.3.2"
}
}
dependencies {
...
// If you're using compose also add the compose extension
implementation 'com.mapbox.extension:maps-compose:11.10.0'
...
}
android {
buildFeatures {
compose = true
}
}
dependencies {
...
// If you're using compose also add the compose extension
implementation("com.mapbox.extension:maps-compose:11.10.0")
...
}
- Because you've edited your Gradle files, click File > Sync Project with Gradle Files in Android Studio.
- Make sure you placed the maven code inside
dependencyResolutionManagement
and notpluginManagement
. Placing the code here will prevent the Mapbox SDK from being accessible and throw errors later down the line. See Part 2: Add the dependency - Step 1: add the Mapbox Maven dependency for more details. - Check
app/res/values/mapbox_access_token.xml
has a token and does not sayYOUR_MAPBOX_ACCESS_TOKEN
. - Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.
- You might have conflicting transitive dependencies. If necessary, you can use
exclude group
to remove certain dependencies (see Exclude transitive dependencies)
Part 3: Add a map
Now add a map to your application. This can be accomplished by either using Jetpack Compose or in Android View:
With the Maps SDK for Android compose extension, you can add a map to your composable:
-
Make sure you added the Mapbox compose extension to your dependencies (see optional Step #6 above)
-
Go to
app
>kotlin+java
and open the top folder. -
Inside the folder, open the
MainActivity.kt
file. -
Delete everything inside the file except the package import on the first line.
-
Lastly, copy and paste the following code block from below and delete the package import line from the example.
This code will create an interactable globe centered over the United States and set the view's zoom level to 2.
package com.mapbox.maps.demo
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.geojson.Point
import com.mapbox.maps.extension.compose.MapboxMap
import com.mapbox.maps.extension.compose.animation.viewport.rememberMapViewportState
public class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContent {
MapboxMap(
Modifier.fillMaxSize(),
mapViewportState = rememberMapViewportState {
setCameraOptions {
zoom(2.0)
center(Point.fromLngLat(-98.0, 39.5))
pitch(0.0)
bearing(0.0)
}
},
)
}
}
}
When using the Mapbox Jetpack Compose Extension, some map plugins—including Compass
, Scalebar
, Logo
, Attribution
, and Lifecycle
—are replaced by their Jetpack Compose counterparts.
As a result, APIs such as mapView.compass
, mapView.scalebar
, mapView.logo
, mapView.attribution
, and mapView.lifecycle
will not function and may result in runtime exceptions. To avoid these issues, use the corresponding Compose APIs instead.
Learn more by seeing our Using Jetpack Compose Guide.
Instantiate a Mapbox map in your Android Activity:
-
Go to
app
>kotlin+java
and open the top folder. -
Inside the folder, open the
MainActivity.kt
file. -
Delete everything inside the file except the package import on the first line.
-
Lastly, copy and paste the following code block from below and delete the package import line from the example.
This code will create that will fill the container with an interactable globe, centered over the United States and set to a zoom level 2.
package com.mapbox.maps.demo
import android.os.Bundle
import androidx.activity.ComponentActivity
import com.mapbox.geojson.Point
import com.mapbox.maps.CameraOptions
import com.mapbox.maps.MapView
class MainActivity : ComponentActivity() {
private lateinit var mapView: MapView
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Create a map programmatically and set the initial camera
mapView = MapView(this)
mapView.mapboxMap.setCamera(
CameraOptions.Builder()
.center(Point.fromLngLat(-98.0, 39.5))
.pitch(0.0)
.zoom(2.0)
.bearing(0.0)
.build()
)
// Add the map view to the activity (you can also add it to other views as a child)
setContentView(mapView)
}
}
Now save your work and start the emulator. Once the emulator is finished loading, you should see an interactable globe:
If your implementation is not working as expected, view the following troubleshooting section:
- Click on File > Save All to make sure you haven't missed any changes.
- Try running File > Sync Project with Gradle Files in case a change had not been synced throughout your project.
- Make sure you are using the correct import package line. If you see
package com.mapbox.maps.demo
in yourMainActivity.kt
, you need to replace with your project's import line. This will typically follow the format of package.com.example.PROJECT_NAME. - If the mapbox library isn't being imported, check the following:
- Check
app/res/values/mapbox_access_token.xml
has a token and does not sayYOUR_MAPBOX_ACCESS_TOKEN
. - Make sure you've added the required dependencies to the
settings.gradle.kts
file andbuild.gradle.kts
match the example snippets seen in Part 2: Add the dependency.
- Check
- Check you've imported the right libraries into the MainActivity file as seen in the example code.
- Switch virtual devices if you can't get your map to show on the default pixel fold.
- Check if you have conflicting transitive dependencies. If necessary, you can use
exclude group
to remove certain dependencies (see Exclude transitive dependencies)_
Next Steps
With the Maps SDK installed and a minimal map rendering in your app, you can explore additional features of the SDK:
- Add a user location puck
- Understand Markers and Map Annotations
- Learn more about the camera and map animations
You can also explore example code and tutorials:
Learn how to clone and run the Mapbox Maps SDK for Android examples app to see any Android example in real time.
Learn how to mark a point of interest on a map by using point annotations.
Learn how to mark a point of interest on a map by using point annotations.