Skip to main content
Make sure you’ve installed Open Mobile Maps before proceeding with this guide.
This guide will walk you through creating a basic map application on both Android and iOS platforms.

​
Android quickstart

1

Add MapView to your layout

Create a layout XML file with a MapView:
activity_main.xml
<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    
    <io.openmobilemaps.mapscore.map.view.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</FrameLayout>
2

Initialize the map

In your Activity or Fragment, set up the MapView:
MainActivity.kt
import io.openmobilemaps.mapscore.map.coordinates.CoordinateSystemFactory
import io.openmobilemaps.mapscore.map.MapConfig
import io.openmobilemaps.mapscore.map.view.MapView

class MainActivity : AppCompatActivity() {
    private lateinit var mapView: MapView
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        mapView = findViewById(R.id.mapView)
        
        // Setup map with EPSG:3857 (Web Mercator) coordinate system
        mapView.setupMap(MapConfig(CoordinateSystemFactory.getEpsg3857System()))
        
        // Register lifecycle
        mapView.registerLifecycle(lifecycle)
    }
}
3

Add a raster tile layer

Add a basic OpenStreetMap tile layer:
import io.openmobilemaps.mapscore.map.layers.tiled.raster.TiledRasterLayer

// Add raster layer (uses default OpenStreetMap tiles)
val tiledRasterLayer = TiledRasterLayer()
mapView.addLayer(tiledRasterLayer)
4

Position the camera

Set the initial camera position and zoom level:
import io.openmobilemaps.mapscore.shared.map.coordinates.Coord
import io.openmobilemaps.mapscore.shared.map.coordinates.CoordinateSystemIdentifiers

// Move camera to a specific location (Bern, Switzerland)
mapView.getCamera().moveToCenterPositionZoom(
    Coord(
        CoordinateSystemIdentifiers.EPSG4326(), 
        7.4474, // longitude
        46.9480, // latitude
        0.0
    ), 
    1000000.0, // zoom level
    false // animated
)

​
iOS quickstart

1

Create a SwiftUI view

Create a new SwiftUI view with MapView:
ContentView.swift
import SwiftUI
import MapCore

struct ContentView: View {
    @State private var camera = MapView.Camera(
        latitude: 46.9480,
        longitude: 7.4474,
        zoom: 1000000
    )
    @State private var layers: [any Layer] = []
    
    var body: some View {
        MapView(
            camera: $camera,
            layers: layers
        )
        .onAppear {
            setupLayers()
        }
    }
    
    private func setupLayers() {
        layers = [
            TiledRasterLayer(
                "osm", 
                webMercatorUrlFormat: "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
            )
        ]
    }
}

​
Customization options

You can replace the OpenStreetMap tile server with your own:
val customLayer = TiledRasterLayer(
    customConfig = object : Tiled2dMapLayerConfig() {
        override fun getTileUrl(x: Int, y: Int, t: Int, zoom: Int): String {
            return "https://your-tile-server.com/$zoom/$x/$y.png"
        }
        // Implement other required methods...
    }
)
Control the minimum and maximum zoom levels:
mapView.getCamera().setMinZoom(5000000.0)
mapView.getCamera().setMaxZoom(300.0)
Configure cache size and referrer for the tile loader:
Android
val dataLoader = DataLoader(
    context = this,
    cacheDirectory = cacheDir,
    maxCacheSize = 50L * 1024L * 1024L, // 50 MB
    referrer = "my-app-referrer"
)

val layer = TiledRasterLayer(dataLoader)

​
Next steps

Platform setup

Platform-specific setup guides

Add layers

Learn about different layer types

Camera controls

Master camera movement and positioning

API reference

Explore the complete API

Build docs developers (and LLMs) love

Get started for freeTalk to us