Skip to content

MapLibre GL Native

Note

This document is not a comprehensive introduction to native development, and assumes you already have basic proficiency in your platform of choice. Most of the APIs are extremely similar to the older open-sourced Mapbox SDKs, so if you are familiar with these or come across examples written using it, most code and principles will still be applicable.

Don't forget to sign up for a free Stadia Maps account so you can try this on your own device!

Get Started With a Free Account

MapLibre GL Native is the best way to build a native app with first-party developer tools such as Xcode or Android Studio.

Quickstart

Warning

All mobile and desktop applications involve making requests using an API key. You must take care to secure this, especially if your app reaches end user outside your organization. See our authentication docs for more details.

iOS

On iOS, you can add the MapLibre package via the built-in Swift Package Manager. Apple provides general instructions in their documentation. The easiest way is to enter the package URL: https://github.com/maplibre/maplibre-gl-native-distribution; searching for the package does not always work.

Once added, all you have to do is add it to your view hierarchy. It works equally well in SwiftUI or plain old UIKit, though note that SwiftUI previews may be broken in some configurations due to a bug in Xcode.

// Get this from somewhere else (see the warning at the top of the page)
let apiKey = "YOUR-API-KEY"

// You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
// provide your own (just make sure to include your API key in the source URL).
let styleID = "outdoors"

// Build the style url
let styleURL = URL(string: "https://tiles.stadiamaps.com/styles/\(styleID).json?api_key=\(apiKey)")

// create the mapview
let mapView = MGLMapView(frame: .zero, styleURL: styleURL)

// This will be unnecessary in a future release, but for now it puts a
// Mapbox logo in the corner, which is not necessary except when using Mapbox tiles.
mapView.logoView.isHidden = true

Android

On Android, the MapLibre GL Native package is available from Maven Central. New Android Studio projects have this repository enabled by default. If it is not enabled, you can add mavenCentral() to your build script.

build.gradle
repositories {
    mavenCentral()
}

Then, add MapLibre to your dependencies.

build.gradle
dependencies {
    implementation 'org.maplibre.gl:android-sdk:9.5.2'
}

Tip

Note that if you are using AndroidX (android.useAndroidX in gradle.properties), you will also need to set android.enableJetifier=true.

You can now add a MapView in to your Activity's XML layout. Here is an example.

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

Finally, configure it in your Activity's onCreate method. Here is a minimal example.

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Required SDK initialization before inflating/creating
    // the map view (MUST come before `setContentView` below)
    Mapbox.getInstance(this)

    setContentView(R.layout.activity_main)

    // Get this from somewhere else (see the warning at the top of the page)
    val apiKey = "YOUR-API-KEY"

    // You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
    // provide your own (just make sure to include your API key in the source URL).
    val styleId = "outdoors"

    // Build the style URL
    val styleUrl = "https://tiles.stadiamaps.com/styles/$styleId.json?api_key=$apiKey"

    // Create map view
    val mapView: MapView? = findViewById(R.id.mapView)
    mapView?.onCreate(savedInstanceState)
    mapView?.getMapAsync { map ->
        // This will be unnecessary in a future release, but for now it puts a
        // Mapbox logo in the corner, which is not necessary except when using Mapbox tiles.
        map.uiSettings.isLogoEnabled = false

        // Set the style after mapView was loaded
        map.setStyle(styleUrl) {
            // Add any extra initialization that requires
            // the style to be loaded here in a closure.
        }
    }
}

Next Steps

This example is just enough to get you started, but doesn't even scratch the surface of the rich APIs available. For more information, the iOS Reference and Android Javadocs are the authoritative sources.

And of course, don't forget to sign up for a free Stadia Maps account, so you can try this on your own device!

Get Started With a Free Account