MapLibre Setup

This section covers the setup process for MapLibre Native Android integration with MapConductor.

Tip

MapConductor provides a unified API layer on top of existing map SDKs. You must set up the MapLibre Native Android SDK independently before using MapConductor’s MapLibre integration.

Prerequisites

• Android development environment
• Tile server URL (e.g., OpenStreetMap, Maptiler, or self-hosted tiles)
• Style JSON URL or configuration

Setup Steps

1. Tile Server Selection

MapLibre is an open-source mapping library that requires a tile server. You have several options:

Free/Community Options:

• OpenStreetMap tiles - Free but requires attribution
• Protomaps - Open data with self-hosting options

Commercial Providers:

• Maptiler - Free tier available
• Stadia Maps - Free tier available
• MapTiler Cloud - Generous free tier

Self-Hosted:

• Run your own tile server using tools like tileserver-gl

2. Gradle Configuration

Add the dependencies to your app’s build.gradle.kts or build.gradle:

Kotlin (build.gradle.kts)

App/build.gradle.kts

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

    // MapConductor BOM for version management (v1.1.3)
    implementation(platform("com.mapconductor:mapconductor-bom:1.1.3"))

    // MapConductor modules (versions managed by BOM)
    implementation("com.mapconductor:core")
    implementation("com.mapconductor:for-maplibre")
}

Groovy (build.gradle)

App/build.gradle

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

    // MapConductor BOM for version management (v1.1.3)
    implementation platform("com.mapconductor:mapconductor-bom:1.1.3")

    // MapConductor modules (versions managed by BOM)
    implementation "com.mapconductor:core"
    implementation "com.mapconductor:for-maplibre"
}

The MapLibre SDK is available from Maven Central, which should already be configured in your settings.gradle.kts or settings.gradle:

Kotlin (settings.gradle.kts)

settings.gradle.kts

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

Groovy (settings.gradle)

settings.gradle

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

3. Android Manifest Configuration

Add the required permissions to your AndroidManifest.xml:

AndroidManifest.xml

<application>


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

4. Style Configuration

MapLibre requires a style JSON to define how the map looks. You can use a hosted style or provide a custom one.

Demo style

val mapDesign = MapLibreDesignType.DemoTiles

Using a hosted style

val mapDesign = MapLibreDesignType(
    "basic map",
    "https://api.maptiler.com/maps/base-v4/style.json?key=YOUR_API_KEY",
)

Using OpenStreetMap style

// Example using OSM Liberty style
val mapDesign = MapLibreDesignType(
    "OpenStreetMap",
    "https://tiles.openfreemap.org/styles/liberty",
)

Verification

To verify your MapLibre setup:

1. Build and run your app
2. Check that the map tiles load correctly
3. Test map interactions (zoom, pan, rotate)
4. Verify attribution is displayed if required by your tile provider

@Composable
fun TestMapLibre() {
    val state = rememberMapLibreMapViewState(
        cameraPosition =
            MapCameraPosition(
                position = GeoPoint.fromLatLong(0.0, 0.0),
                zoom = 3.0,
            ),
        mapDesign = MapLibreDesignType(
            "basic map",
            "https://api.maptiler.com/maps/base-v4/style.json?key=API_KEY_FOR_MAPTILER",
        ),
    )

    MapLibreMapView(
        modifier = modifier,
        state = state,
    ) {
        // If this displays correctly, your setup is working
    }
}

Troubleshooting

Common Issues

Map not displaying (blank screen)

• Verify the style URL is accessible and correct
• Check internet connectivity for tile loading
• Ensure the style JSON is valid
• Check Logcat for network or parsing errors

Tiles not loading

• Verify your tile server URL is correct
• Check rate limits for free tile services
• Ensure proper API key if using commercial providers
• Verify network permissions are granted

Attribution missing

• Most tile providers require attribution to be displayed
• Check your tile provider’s terms of service
• Add proper attribution text to your UI

Build errors

• Ensure MapLibre SDK version is compatible
• Verify Maven Central repository is configured
• Check for dependency conflicts with other map SDKs

Attribution Requirements

Many tile servers require attribution. Common examples:

• OpenStreetMap: ”© OpenStreetMap contributors”
• Maptiler: ”© MapTiler © OpenStreetMap contributors”
• Stadia Maps: Check their specific requirements

Make sure to display required attributions in your app UI according to your tile provider’s terms.

Performance Tips

• Use vector tiles when possible for better performance and smaller downloads
• Consider caching tiles for offline use
• Use appropriate zoom levels for your use case
• Monitor network usage if using metered connections

Next Steps

Once MapLibre is properly configured, you can use MapConductor’s MapLibreMapView component with the unified API.