MapLibre Native¶

Free

Starter

Standard

Professional

If you're building a native mobile application, MapLibre 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¶

SwiftUI¶

We're leading the development of a SwiftUI DSL for MapLibre. To get started, add the Swift Packgae dependency to your project. The repo URL is https://github.com/stadiamaps/maplibre-swiftui-dsl-playground.

Here's a quick example to get started:

import MapLibre
import MapLibreSwiftUI
import MapLibreSwiftDSL
import SwiftUI

public struct MyView {
    // Be sure to store this securely (1)
    let apiKey = "YOUR-API-KEY"

    // You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
    // provide your own.
    let styleID = "outdoors"

    // A collection of points with various attributes
    let pointSource = ShapeSource(identifier: "points") {
        // Uses the DSL to quickly construct point features inline
        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 51.47778, longitude: -0.00139))

        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 0, longitude: 0)) { feature in
            feature.attributes["heading"] = 45
        }

        MLNPointFeature(coordinate: CLLocationCoordinate2D(latitude: 39.02001, longitude: 1.482148)) { feature in
            feature.attributes["heading"] = 145
        }
    }

    @State var camera = MapViewCamera.center(
        CLLocationCoordinate2D(latitude: 48.2082, longitude: 16.3719),
        zoom: 5,
        direction: 0
    )

    public var body: some View {
        MapView(styleURL: demoTilesURL) {
            // Symbol layer demonstration with an icon rendered for each point.
            // The rotation is dynamically selected from the attributes associtaed with each point feature.
            SymbolStyleLayer(identifier: "rotated-symbols", source: pointSource)
                .iconImage(UIImage(systemName: "location.north.circle.fill")!)
                .iconRotation(featurePropertyNamed: "heading")
        }
        .ignoresSafeArea(.all)
    }    
}

Learn how to get an API key in our authentication guide.

The Swift Package is broken up into a few modules:

MapLibreSwiftUI - High level SwiftUI views
MapLibreSwiftDSL - A more Swift-y set of APIs for things like layers and expressions (making MapLibre more convenient to use)
MapLibre - The MapLibre Native library

The SwiftUI DSL doesn't have every single feature of the lower level MapLibre UIKit library yet, but it covers the most common APIs already and will make your SwiftUI integration a lot more pleasant. In case you need some feature that isn't in the high-level interface yet, the SwiftUI MapView has an unsafeMapViewControllerModifier(_:) extension method. This will give you raw access to the internals, so your important work won't be blocked by a missing API.

UIKit¶

Building a UIKit-based app? You can add the MapLibre package directly via the built-in Swift Package Manager. 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. Here's a skeleton to get you started.

// Import (at the top of your file)
import MapLibre

// Be sure to store this securely (1)
let apiKey = "YOUR-API-KEY"

// You can find other styles in our library (https://docs.stadiamaps.com/themes/) or
// provide your own.
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 = MLNMapView(frame: .zero, styleURL: styleURL)

Learn how to get an API key in our authentication guide.

From here, we recommend checking out the official MapLibre iOS Documentation, which is also full of example snippets!

Android¶

On Android, the MapLibre 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:10.2.0'
}

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)

    // Be sure to store this securely (1)
    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.
        }
    }
}

Learn how to get an API key in our authentication guide.

Using Jetpack Compose?

If you're developing your app with Jetpack Compose, check out Ramani Maps. This project is the spiritual twin of our SwiftUI DSL for the Android world. We've already contributed some improvements back to the project ourselves, and recommend taking a look if you're building a Compose app.

Next Steps¶

This example is just enough to get you started, but doesn't even scratch the surface of the rich APIs that MapLibre Native offers. For more information, refer to the official iOS and Android references.