Mapbox Android Patterns

Official integration patterns for Mapbox Maps SDK on Android. Covers installation, adding markers, user location, custom data, styles, camera control, and fe...

Security Scan

The skill's files and runtime instructions align with its stated purpose (Mapbox Maps SDK Android integration patterns); it requests no secrets, installs no software, and stays within expected scope.

Purpose & Capability

Name and description match the provided SKILL.md and reference files: all content is Android + Mapbox SDK v11 integration patterns (installation, annotations, location, styles, camera, interactions). There are no unrelated required binaries, env vars, or config paths.

Instruction Scope

SKILL.md and reference docs only instruct typical developer actions: add the Mapbox Maven repo, add dependencies, place an access token in app resources, request location permissions, and use Mapbox APIs. No instructions ask the agent to read arbitrary host files, export secrets, or contact endpoints other than Mapbox official docs and Mapbox's Maven URL.

Install Mechanism

This is instruction-only with no install spec and no code to execute or download; nothing is written to disk by the skill itself.

Credentials

The skill declares no environment variables, credentials, or config paths. The only secret referenced is the Mapbox access token, and its suggested placement in app/res/values is consistent with the SDK usage described.

Persistence & Privilege

always is false and there are no install-time persistence actions. The skill does not request elevated platform privileges or attempt to modify other skills or system-wide settings.

Assessment

This appears to be a straightforward, coherent documentation-style skill for Mapbox Android integration. Before using the patterns in a real app: avoid committing your Mapbox access token to public repos (consider build-time secrets or Android Secret Manager), verify the dependency version (11.18.1 in the docs) and the Mapbox Maven URL are the intended official endpoints, and review location-permission handling to meet user-privacy requirements.

Mapbox Android Integration Patterns

Official patterns for integrating Mapbox Maps SDK v11 on Android with Kotlin, Jetpack Compose, and View system.

Use this skill when:

• Installing and configuring Mapbox Maps SDK for Android
• Adding markers and annotations to maps
• Showing user location and tracking with camera
• Adding custom data (GeoJSON) to maps
• Working with map styles, camera, or user interaction
• Handling feature interactions and taps

Official Resources:

• Android Maps Guides
• API Reference
• Example Apps

---

Installation & Setup

Requirements

• Android SDK 21+
• Kotlin or Java
• Android Studio
• Free Mapbox account

Step 1: Configure Access Token

Create app/res/values/mapbox_access_token.xml:

<?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>

Get your token: Sign in at mapbox.com

Step 2: Add Maven Repository

In settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
        }
    }
}

Step 3: Add Dependency

In module build.gradle.kts:

android {
    defaultConfig {
        minSdk = 21
    }
}

dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
}

For Jetpack Compose:

dependencies {
    implementation("com.mapbox.maps:android:11.18.1")
    implementation("com.mapbox.extension:maps-compose:11.18.1")
}

---

Map Initialization

Jetpack Compose Pattern

Basic map:

import androidx.compose.runtime.*
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.Modifier
import com.mapbox.maps.extension.compose.*
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

@Composable
fun MapScreen() {
    MapboxMap(
        modifier = Modifier.fillMaxSize()
    ) {
        // Initialize camera via MapEffect (Style.STANDARD loads by default)
        MapEffect(Unit) { mapView ->
            // Set initial camera position
            mapView.mapboxMap.setCamera(
                CameraOptions.Builder()
                    .center(Point.fromLngLat(-122.4194, 37.7749))
                    .zoom(12.0)
                    .build()
            )
        }
    }
}

With ornaments:

MapboxMap(
    modifier = Modifier.fillMaxSize(),
    scaleBar = {
        ScaleBar(
            enabled = true,
            position = Alignment.BottomStart
        )
    },
    compass = {
        Compass(enabled = true)
    }
) {
    // Style.STANDARD loads by default
}

View System Pattern

Layout XML (activity_map.xml):

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Activity:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.mapbox.maps.MapView
import com.mapbox.maps.Style
import com.mapbox.geojson.Point

class MapActivity : AppCompatActivity() {
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)

        mapView = findViewById(R.id.mapView)

        mapView.mapboxMap.setCamera(
            CameraOptions.Builder()
                .center(Point.fromLngLat(-122.4194, 37.7749))
                .zoom(12.0)
                .build()
        )

        mapView.mapboxMap.loadStyle(Style.STANDARD)
    }

    override fun onStart() {
        super.onStart()
        mapView.onStart()
    }

    override fun onStop() {
        super.onStop()
        mapView.onStop()
    }

    override fun onDestroy() {
        super.onDestroy()
        mapView.onDestroy()
    }
}

---

Add Markers (Point Annotations)

Point annotations are the most common way to mark locations on the map.

Jetpack Compose:

MapboxMap(modifier = Modifier.fillMaxSize()) {
    MapEffect(Unit) { mapView ->
        // Load style first
        mapView.mapboxMap.loadStyle(Style.STANDARD)

        // Create annotation manager and add markers
        val annotationManager = mapView.annotations.createPointAnnotationManager()
        val pointAnnotation = PointAnnotationOptions()
            .withPoint(Point.fromLngLat(-122.4194, 37.7749))
            .withIconImage("custom-marker")
        annotationManager.create(pointAnnotation)
    }
}

// Note: Compose doesn't have declarative PointAnnotation component
// Markers must be added imperatively via MapEffect

View System:

// Create annotation manager (once, reuse for updates)
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

// Create marker
val pointAnnotation = PointAnnotationOptions()
    .withPoint(Point.fromLngLat(-122.4194, 37.7749))
    .withIconImage("custom-marker")

pointAnnotationManager.create(pointAnnotation)

Multiple markers:

val locations = listOf(
    Point.fromLngLat(-122.4194, 37.7749),
    Point.fromLngLat(-122.4094, 37.7849),
    Point.fromLngLat(-122.4294, 37.7649)
)

val annotations = locations.map { point ->
    PointAnnotationOptions()
        .withPoint(point)
        .withIconImage("marker")
}

pointAnnotationManager.create(annotations)

---

Show User Location (Display)

Step 1: Add permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Step 2: Request permissions and show location:

// Request permissions first (use ActivityResultContracts)

// Show location puck
mapView.location.updateSettings {
    enabled = true
    puckBearingEnabled = true
}

---

Performance Best Practices

Reuse Annotation Managers

// Don't create new managers repeatedly
// val manager = mapView.annotations.createPointAnnotationManager() // each call

// Create once, reuse
val pointAnnotationManager = mapView.annotations.createPointAnnotationManager()

fun updateMarkers() {
    pointAnnotationManager.deleteAll()
    pointAnnotationManager.create(markers)
}

Batch Annotation Updates

// Create all at once
pointAnnotationManager.create(allAnnotations)

// Don't create one by one in a loop

Lifecycle Management

// Always call lifecycle methods
override fun onStart() {
    super.onStart()
    mapView.onStart()
}

override fun onStop() {
    super.onStop()
    mapView.onStop()
}

override fun onDestroy() {
    super.onDestroy()
    mapView.onDestroy()
}

Use Standard Style

// Standard style is optimized and recommended
Style.STANDARD

// Use other styles only when needed for specific use cases
Style.STANDARD_SATELLITE // Satellite imagery

---

Troubleshooting

Map Not Displaying

Check:

1. Token in mapbox_access_token.xml
2. Token is valid (test at mapbox.com)
3. Maven repository configured
4. Dependency added correctly
5. Internet permission in manifest

Style Not Loading

mapView.mapboxMap.subscribeStyleLoaded { _ ->
    Log.d("Map", "Style loaded successfully")
    // Add layers and sources here
}

Performance Issues

• Use Style.STANDARD (recommended and optimized)
• Limit visible annotations to viewport
• Reuse annotation managers
• Avoid frequent style reloads
• Call lifecycle methods (onStart, onStop, onDestroy)
• Batch annotation updates

---

Reference Files

Load these references when you need detailed patterns for specific topics:

• references/annotations.md -- Circle, Polyline, and Polygon annotation patterns
• references/location-tracking.md -- Camera follow user location + get current location once
• references/custom-data.md -- GeoJSON sources and layers: lines, polygons, points, update/remove
• references/camera-styles.md -- Camera control (set, animate, fit) + map styles (built-in and custom)
• references/interactions.md -- Featureset interactions, custom layer taps, long press, gestures

---

Additional Resources

• Android Maps Guides
• API Reference
• Interactions Guide
• Jetpack Compose Guide
• Example Apps
• Migration Guide (v10 -> v11)