OpenMapView

A modern, Kotlin-first MapView replacement for Android — powered by OpenStreetMap.

Installation

Add to your build.gradle.kts:

dependencies {
    implementation("de.afarber:openmapview:0.6.0")
}

The library is available on Maven Central. Alternative distribution via JitPack is also supported.

Features

• Drop-in compatible with Google MapView (non-deprecated methods only)
• Lightweight, pure Kotlin implementation
• OSM tiles via standard APIs
• Smooth camera animations with customizable durations
• Extensible marker, overlay, and gesture handling
• MIT licensed (use freely in commercial apps)

API Documentation

Full API reference documentation is available at afarber.github.io/OpenMapView.

The documentation is automatically generated from KDoc comments and updated with every commit to main.

Examples

Explore the example applications to see OpenMapView in action:

• Example01Pan - Basic map panning with touch gestures
• Example02Zoom - Zoom controls and pinch-to-zoom
• Example03Markers - Marker overlays with custom icons
• Example04Polylines - Polylines, polygons, and polygons with holes
• Example05Camera - Camera animations with callbacks
• Example06Clicks - Map click and long-click listeners
• Example07DraggableMarkers - Draggable markers with drag event listeners
• Example08Circles - Circles with various radii, styling, and z-index ordering
• Example09Overlays - Tile overlays with transparency control (OpenSeaMap, OpenRailwayMap, Hiking Trails, OpenSnowMap)
• Example10GroundOverlays - Ground overlays with position/bounds modes, rotation, and transparency
• Example11MapTypes - Switching between map types (Normal, Terrain, Humanitarian, Cycle)

Documentation

• Public API Compatibility - Google MapView API implementation status and compatibility matrix
• Architecture - Architectural design and comparison with Google Maps SDK
• Contributing Guide - Code quality requirements, formatting, git hooks, and PR process
• Lifecycle Management - How OpenMapView handles Android lifecycle events
• Publishing Guide - Publishing to Maven Central and JitPack
• GitHub Workflows - CI/CD pipeline and workflow architecture
• Unit Testing - JVM unit tests with Robolectric for Android framework APIs
• Instrumented Testing - On-device (phone and auto) testing with Android emulator

Getting Started

With Jetpack Compose

@Composable
fun MapViewScreen() {
    val lifecycleOwner = androidx.lifecycle.compose.LocalLifecycleOwner.current

    AndroidView(
        factory = { context ->
            OpenMapView(context).apply {
                // Register lifecycle observer for proper cleanup
                lifecycleOwner.lifecycle.addObserver(this)

                setCenter(LatLng(51.4661, 7.2491))
                setZoom(14.0)

                // Add markers - Kotlin style (direct instantiation)
                addMarker(Marker(
                    position = LatLng(51.4661, 7.2491),
                    title = "Bochum City Center"
                ))

                // Or Google Maps API style (builder pattern)
                addMarker(
                    MarkerOptions()
                        .position(LatLng(51.4700, 7.2550))
                        .title("North Location")
                        .draggable(true)
                )
            }
        },
        modifier = Modifier.fillMaxSize()
    )
}

With XML Layouts

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val mapView = findViewById<OpenMapView>(R.id.mapView)
        mapView.setZoom(14.0)
        mapView.setCenter(LatLng(51.4661, 7.2491))
    }
}