Organic Maps Android API

A thin Java library that wraps the Organic Maps deep-link API so your app (Java or Kotlin) can:

• show one or more points of interest on the offline map in Organic Maps;
• let the user pick a point on that map and receive its coordinates back via Activity Result;
• brand the map screen with your app's name as a title.

Two-way communication between your app and Organic Maps lets you use OM as the map UI while keeping the user's tap inside your own activity stack.

The library is convenience over deep links. You can also build the om:// URIs yourself; read MapRequest.java / CrosshairRequest.java for the format.

Prerequisites

• Familiarity with Android development, Intents, and the Activity Result APIs.
• Organic Maps runs on Android 5 (SDK 21) and above.

Setup

Clone the repo and add :lib as a Gradle module of your project — or build the AAR yourself:

./gradlew :lib:assembleRelease   # produces lib/build/outputs/aar/lib-release.aar

No additional permissions are required in your AndroidManifest.xml.

The two samples in this repo are good starting points:

Module	Demonstrates
:sample-app-capitals	Show many points and round-trip the user's pick back to your app.
:sample-pick-point	Crosshair pick using the modern ActivityResultLauncher flow.

Core classes

• OrganicMapsApi — entry point with showPointOnMap / showPointsOnMap / sendRequest helpers and canHandleOrganicMapsIntents / isOrganicMapsPackageInstalled probes.
• MapRequest — fluent builder for om://map?… intents. Call setPickPointMode(true) to ask OM to return the picked point.
• CrosshairRequest — fluent builder for om://crosshair?… intents (always pick-point).
• Point — POI model: lat, lon, name, optional id, optional Style.
• PickPointResponse — parses the result intent into a Point plus the zoom level.

Show points on the map

Java

// Single point — title defaults to the point name.
OrganicMapsApi.showPointOnMap(this, lat, lon, "Eiffel Tower");

// Multiple points with a custom title.
final ArrayList<Point> points = new ArrayList<>();
for (SomeDomainObject obj : list)
  points.add(new Point(obj.lat, obj.lon, obj.name));
OrganicMapsApi.showPointsOnMap(this, "Capitals of the World", points);

Kotlin

// Single point — title defaults to the point name.
OrganicMapsApi.showPointOnMap(this, lat, lon, "Eiffel Tower")

// Multiple points with a custom title. showPointsOnMap takes ArrayList<Point>,
// so mapTo(ArrayList()) instead of plain map { ... }.
val points = list.mapTo(ArrayList(list.size)) { Point(it.lat, it.lon, it.name) }
OrganicMapsApi.showPointsOnMap(this, "Capitals of the World", points)

If Organic Maps is not installed, the library shows a download dialog instead of crashing.

Round-trip: let the user pick a point

Register an ActivityResultLauncher and launch a MapRequest (or CrosshairRequest) with pick-point mode enabled.

Java

private final ActivityResultLauncher<Intent> pickPoint = registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    result -> {
      if (result.getResultCode() != RESULT_OK || result.getData() == null)
        return;
      final PickPointResponse response = PickPointResponse.extractFromIntent(result.getData());
      if (response == null)
        return;
      final Point point = response.getPoint();
      // point.getId() lets you map the result back to your domain object.
      onUserPicked(point, response.getZoomLevel());
    });

void launchPicker(List<MyPoi> pois)
{
  final ArrayList<Point> points = new ArrayList<>(pois.size());
  for (MyPoi poi : pois)
    points.add(new Point(poi.lat, poi.lon, poi.name, poi.id));

  final Intent intent = new MapRequest()
      .setAppName(getString(R.string.app_name))
      .setPoints(points)
      .setPickPointMode(true)        // ask OM to send the picked point back
      .toIntent();

  if (!OrganicMapsApi.canHandleOrganicMapsIntents(this))
  {
    new DownloadDialog(this).show();
    return;
  }
  pickPoint.launch(intent);
}

Kotlin

Java getters are exposed as Kotlin properties: response.point, point.id, response.zoomLevel.

private val pickPoint = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode != RESULT_OK) return@registerForActivityResult
    val data = result.data ?: return@registerForActivityResult
    val response = PickPointResponse.extractFromIntent(data) ?: return@registerForActivityResult
    val point = response.point
    // point.id lets you map the result back to your domain object.
    onUserPicked(point, response.zoomLevel)
}

private fun launchPicker(pois: List<MyPoi>) {
    val points = pois.mapTo(ArrayList(pois.size)) {
        Point(it.lat, it.lon, it.name, it.id)
    }

    val intent = MapRequest()
        .setAppName(getString(R.string.app_name))
        .setPoints(points)
        .setPickPointMode(true)        // ask OM to send the picked point back
        .toIntent()

    if (!OrganicMapsApi.canHandleOrganicMapsIntents(this)) {
        DownloadDialog(this).show()
        return
    }
    pickPoint.launch(intent)
}

For a free-form pick (no candidate points) use CrosshairRequest instead — see sample-pick-point/MainActivity:

val intent = CrosshairRequest()
    .setAppName(getString(R.string.app_name))
    .toIntent()
pickPoint.launch(intent)

FAQ

Which versions of Organic Maps support this API?

All versions since 2022-07-26.

What happens if Organic Maps is not installed?

OrganicMapsApi.sendRequest (and the manual flow above) falls back to DownloadDialog, which links to https://omaps.app/get?api.

Can I check beforehand whether Organic Maps will handle the intent?

Yes — OrganicMapsApi.canHandleOrganicMapsIntents(context) does a resolveActivity. OrganicMapsApi.isOrganicMapsPackageInstalled(context) checks for the known package IDs (app.organicmaps, .beta, .debug, .web).

License

Copyright (c) 2026, Organic Maps OÜ.

Copyright (c) 2019, MY.COM B.V.

Copyright (c) 2013, MapsWithMe GmbH.

All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.