Skip to main content
This guide covers the complete setup process for integrating Open Mobile Maps into your Android application.

​
Requirements

  • Android 8.0+ (API level 26+)
  • OpenGL ES 3.2
  • Kotlin or Java

​
Installation

1

Add Maven Central repository

Ensure mavenCentral() is listed in your project repositories (typically in settings.gradle or root build.gradle):
settings.gradle
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
2

Add dependency

Add the Open Mobile Maps dependency to your app’s build.gradle:
build.gradle
dependencies {
    implementation 'io.openmobilemaps:mapscore:3.7.1'
}
Check Maven Central for the latest version.
3

Add required dependencies (local .aar only)

If you’re using a local .aar file instead of the Maven dependency, you’ll need to manually add these dependencies:
build.gradle
dependencies {
    implementation "androidx.activity:activity-ktx:1.8.2"
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.7.0"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
    implementation 'com.squareup.okhttp3:okhttp:4.12.0' // used for the default DataLoader
}
These dependencies are automatically included when using the Maven Central dependency.

​
Local installation

Alternatively, you can include the library as a local module or .aar file: 
// Include the android folder as a module in your project
// Then add it as a dependency in your app's build.gradle
dependencies {
    implementation project(':maps-core-android')
}

​
Initialize the library

Initialize the library as early as possible in your application lifecycle, typically in your Application class’s onCreate() method:
Application.kt
import io.openmobilemaps.mapscore.MapsCore

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        MapsCore.initialize()
    }
}
Make sure to register your custom Application class in AndroidManifest.xml:
<application
    android:name=".MyApplication"
    ...>

​
Set up MapView

The MapView is the main UI component for displaying maps.
1

Add MapView to your layout

Add the MapView to your activity or fragment layout:
activity_map.xml
<io.openmobilemaps.mapscore.MapView
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />
2

Configure MapView in your Activity

Set up the MapView with a coordinate system and register it to the lifecycle:
MapActivity.kt
import io.openmobilemaps.mapscore.MapView
import io.openmobilemaps.mapscore.map.MapConfig
import io.openmobilemaps.mapscore.map.coordinates.CoordinateSystemFactory

class MapActivity : AppCompatActivity() {
    private lateinit var mapView: MapView

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_map)

        mapView = findViewById(R.id.mapView)
        
        // Initialize with web mercator coordinate system (EPSG:3857)
        mapView.setupMap(MapConfig(CoordinateSystemFactory.getEpsg3857System()))
        
        // Register to lifecycle for proper handling of pause/resume
        mapView.registerLifecycle(lifecycle)
    }
}
The MapConfig specifies the coordinate system that the camera operates in. EPSG:3857 (Web Mercator) is the most common choice for web-based map tiles.
3

Add a raster layer

Add a tiled raster layer to display map tiles:
import io.openmobilemaps.mapscore.layers.TiledRasterLayer

// Add a raster layer with default settings
val tiledRasterLayer = TiledRasterLayer()
mapView.addLayer(tiledRasterLayer)
For custom configuration with a DataLoader:
import io.openmobilemaps.mapscore.loader.DataLoader

// Create a custom DataLoader with cache settings
val dataLoader = DataLoader(
    context = this,
    cacheDir = cacheDir,
    maxCacheSize = 50L * 1024L * 1024L, // 50MB
    referrer = "your-app-name"
)

val tiledRasterLayer = TiledRasterLayer(dataLoader)
mapView.addLayer(tiledRasterLayer)
4

Set camera position

Position the camera to show a specific location:
import io.openmobilemaps.mapscore.map.coordinates.Coord
import io.openmobilemaps.mapscore.map.coordinates.CoordinateSystemIdentifiers

mapView.getCamera().moveToCenterPositionZoom(
    Coord(
        CoordinateSystemIdentifiers.EPSG4326(),
        8.378232525377973,  // longitude
        46.962592372639634, // latitude
        0.0                  // altitude
    ),
    10000000.0, // zoom level
    false       // animated
)

​
Add vector tiles

Open Mobile Maps supports the Vector Tiles standard: 
import io.openmobilemaps.mapscore.layers.TiledVectorLayer

val tiledVectorLayer = TiledVectorLayer(
    context,
    "https://www.sample.org/base-map/style.json"
)
mapView.add(tiledVectorLayer)
Font data for vector layers is loaded via the FontLoaderInterface and not via URLs in the style.json. See the FontLoader.kt class for implementation details.

​
Custom layer configuration

Create a custom layer configuration for different tile services: 
private val customConfig = object : Tiled2dMapLayerConfig() {
    val epsg3857Bounds: RectCoord = RectCoord(
        Coord(CoordinateSystemIdentifiers.EPSG3857(), -20037508.34, 20037508.34, 0.0),
        Coord(CoordinateSystemIdentifiers.EPSG3857(), 20037508.34, -20037508.34, 0.0)
    )

    override fun getCoordinateSystemIdentifier(): Int = 
        CoordinateSystemIdentifiers.EPSG3857()

    override fun getLayerName(): String = "OSM_Layer"

    override fun getTileUrl(x: Int, y: Int, t: Int, zoom: Int): String {
        return "https://a.tile.openstreetmap.org/$zoom/$x/$y.png"
    }

    override fun getZoomInfo(): Tiled2dMapZoomInfo {
        return Tiled2dMapZoomInfo(
            zoomLevelScaleFactor = 0.6667f,
            numDrawPreviousLayers = 2,
            numDrawPreviousOrLaterTLayers = 0,
            adaptScaleToScreen = true,
            maskTile = false,
            underzoom = true,
            overzoom = true
        )
    }

    override fun getZoomLevelInfos(): ArrayList<Tiled2dMapZoomLevelInfo> = ArrayList(
        listOf(
            Tiled2dMapZoomLevelInfo(559082264.029, 40075016f, 1, 1, 1, 0, epsg3857Bounds),
            Tiled2dMapZoomLevelInfo(279541132.015, 20037508f, 2, 2, 1, 1, epsg3857Bounds),
            // ... additional zoom levels
        )
    )
}

​
WMTS support

Parse WMTS capabilities to create layer configurations: 
import io.openmobilemaps.mapscore.wmts.WmtsCapabilitiesResource

val resource = WmtsCapabilitiesResource.create(xml)
val layer = resource.createLayer("identifier", dataLoader)
mapView.addLayer(layer.asLayerInterface())

​
Camera controls

Set zoom limits for the camera: 
mapView.getCamera().setMinZoom(5000000.0)
mapView.getCamera().setMaxZoom(300.0)
The MapView must be ready and running before camera operations. Use the mapViewState StateFlow to check the current MapViewState.

​
Next steps

Add layers

Learn how to add and customize map layers

Handle interactions

Implement user interactions and gestures

Build docs developers (and LLMs) love

Get started for freeTalk to us