MapLibre GL Native¶

Free

Starter

Standard

Professional

If you're building a native mobile application, MapLibre GL Native is the library you need. In this tutorial, we'll show you how to get a map in your existing application in as few steps as possible.

Before we get started though, you'll need a Stadia Maps API key. You can sign up for free, and no credit card is required! After signing up, create a property and create an API key (there's a button at the bottom of the page).

Get Started With a Free Account

Quickstart¶

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 that MapLibre GL Native offers. For more information, the iOS Reference and Android Javadocs are the authoritative sources.