Docs / Setup / Android / MapLibre

MapLibre setup

How to drive MapLibre Native Android through MapConductor. MapLibre itself has no API key — the look of the map comes from wherever the style JSON is served. This is the shortest setup of them all.

MODULE

com.mapconductor:for-maplibre

API KEY

None

VIEW

MapLibreMapView

TIME

5 min

Same provider, other platformsiOS React

View demoStore Map · React ↗

Before you start

An Android development environment (Android Studio)

A style JSON URL — demo tiles, a commercial service, or your own host

STEP 01

Decide where the tiles come from

MapLibre renders tiles, it does not serve them. The demo styles on MapLibreDesign are enough to verify your setup, but production needs a deliberate choice of source.

Free / community: OpenStreetMap-based tiles, Protomaps (self-hostable)
Commercial: MapTiler Cloud, Stadia Maps (both have free tiers)
Self-hosted: run your own with something like tileserver-gl

CAUTION

Demo tiles are for verification only — never point production traffic at them. Most tile sources also require attribution (e.g. “© OpenStreetMap contributors”); check the terms and surface it in your UI.

STEP 02

Add the dependencies

The MapLibre SDK comes from Maven Central, so no extra repository configuration is needed.

settings.gradle.ktsKotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

app/build.gradle.ktsKotlin

dependencies {
    // MapLibre Native Android SDK
    implementation("org.maplibre.gl:android-sdk:13.3.0")

    // MapConductor BOM pins every module below
    implementation(platform("com.mapconductor:mapconductor-bom:1.2.0"))

    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-maplibre")
}

STEP 03

Add permissions to the manifest

There is no key to inject, so permissions are all that is needed.

AndroidManifest.xmlXML

<manifest>
    <!-- Add internet permission for tile loading -->
    <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" />

    <application>
        <!-- no key to inject for MapLibre -->
    </application>
</manifest>

The ACCESS_*_LOCATION permissions are only needed if your app uses location. Fetching tiles needs INTERNET alone.

VERIFY

What you should see

Render the map with a style. If tiles load and zoom, pan and rotate all work, you are done.

TestMapLibre.ktJetpack Compose

@Composable
fun TestMapLibre(modifier: Modifier = Modifier) {
    val mapState = rememberMapLibreMapViewState(
        cameraPosition = MapCameraPosition(
            position = GeoPoint(35.6762, 139.6503),
            zoom = 12.0,
        ),
        mapDesign = MapLibreDesign.OpenMapTiles,
    )

    // If the map appears, the setup is correct.
    MapLibreMapView(modifier = modifier, state = mapState)
}

Map designs

Each MapLibreDesign wraps a style JSON URL. Point it at your own style by constructing the same type.

MapLibreDesign

Notes

DemoTiles

MapLibre's own demo tiles — no key, fastest path to a working map

OsmBright / OsmBrightEn / OsmBrightJa

OSM Bright, in default / English / Japanese label variants

MapTilerTonerEn / MapTilerTonerJa

The high-contrast Toner style

MapTilerBasicEn / MapTilerBasicJa

The pared-back Basic style

OpenMapTiles

The generic OpenMapTiles style

Troubleshooting

The map stays blank

Check the style URL is reachable and the JSON is valid.
Confirm the INTERNET permission is present.
Look for network or parse errors in Logcat.

Tiles specifically fail to load

Double-check the tile server URL.
Check whether you are hitting a free tier's rate limit.
For a commercial provider, verify the key embedded in the style URL is still valid.

The build fails

Check that the map SDK coordinates and version match what your version catalog declares.
Make sure the repository is declared in settings.gradle.kts — with repositoriesMode set to FAIL_ON_PROJECT_REPOS, per-module repositories blocks are ignored.
If several map SDKs are present at once, look for dependency clashes with ./gradlew :app:dependencies.

Vector tiles are smaller and render faster than raster. If you need offline use, plan for tile caching.