Valhalla Mobile

This project builds valhalla as a static iOS or shared Android library.

It currently exposes valhalla's route action, for the primary purpose of generating turn by turn navigation routes using a downloaded pre-parsed valhalla tileset, along with the two map matching actions — trace_route, which snaps a GPS trace to the road network and returns a route along it, and trace_attributes, which returns the attributes of every edge the trace matched — height, which samples elevations under a shape, and sources_to_targets, which computes a matrix of costs and times between every source and every target. All of them run entirely against the tiles on the device.

Supported actions

Feature	Valhalla action	Android	iOS
Routing	route	✅	✅
Map matching	trace_route	✅	✅
	trace_attributes	✅	✅
Elevation	height	✅	✅
Time-distance matrix	sources_to_targets	✅	✅
Optimized route	optimized_route	–	–
Isochrones	isochrone	–	–
Nearest edge or node	locate	–	–
Graph expansion	expansion	–	–

Responses are valhalla's own JSON on both platforms, decoded into generated model types. route can also answer in the OSRM format, decoded on Android and returned as raw JSON on iOS. GPX is reachable through the raw request methods, which every action has on both platforms. PBF is not supported; requesting it returns an error. height needs a directory of elevation tiles in the config; without them every height is null.

Documentation

Android (Kotlin)

API reference (Dokka)

• Fetching a route, response formats, and errors
• Managing tile files on the device
• Building a valhalla config

iOS (Swift)

API reference (DocC): installation, offline tiles, configuration, and fetching a route.

This repository

• docs/development.md: local toolchain setup, including the NDK version CI uses.
• docs/src/architecture.md: how the C++, JNI, and Obj-C++ layers fit together.
• docs/src/bumping-valhalla.md: upgrading the valhalla submodule.

We welcome contributions to expand the functionality of this library. See our CONTRIBUTING.md for more information. If you've got questions, would like to have informal discussions, or just want to ping us about a question, PR. Feel free to reach out on the OpenStreetMap Slack (osmus.slack.com) under the #valhalla-mobile channel.

Setup

Android

You need the engine plus the model packages; the models define the request and config types your code compiles against.

Using a libs.versions.toml with a build.gradle.kts

[versions]
valhallaMobile = "0.6.1"
valhallaModels = "0.5.2"
osrm = "0.0.10"

[libraries]
valhalla-mobile = { group = "io.github.rallista", name = "valhalla-mobile", version.ref = "valhallaMobile" }
valhalla-models = { group = "io.github.rallista", name = "valhalla-models", version.ref = "valhallaModels" }
valhalla-models-config = { group = "io.github.rallista", name = "valhalla-models-config", version.ref = "valhallaModels" }
osrm-openapi = { group = "com.stadiamaps", name = "osrm-openapi", version.ref = "osrm" }

implementation(libs.valhalla.mobile)
implementation(libs.valhalla.models)
implementation(libs.valhalla.models.config)
implementation(libs.osrm.openapi) // Only needed for the OSRM branch of ValhallaResponse.

Using a standard build.gradle.kts

implementation("io.github.rallista:valhalla-mobile:0.6.1")
implementation("io.github.rallista:valhalla-models:0.5.2")
implementation("io.github.rallista:valhalla-models-config:0.5.2")
implementation("com.stadiamaps:osrm-openapi:0.0.10")

Using a standard build.gradle

implementation 'io.github.rallista:valhalla-mobile:0.6.1'
implementation 'io.github.rallista:valhalla-models:0.5.2'
implementation 'io.github.rallista:valhalla-models-config:0.5.2'
implementation 'com.stadiamaps:osrm-openapi:0.0.10'

iOS

In a swift package:

let package = Package(
    dependencies: [
        .package(url: "https://github.com/rallista/valhalla-mobile.git", from: "0.6.1"),
    ],
    targets: [
        .target(
            dependencies: [
                .product(name: "Valhalla", package: "valhalla-mobile")
            ]
        ),
    ]
)

Manually Building Valhalla C++

Fetching submodules

git submodule update --init --recursive

Set up VCPKG

git clone https://github.com/microsoft/vcpkg && git -C vcpkg checkout 2025.12.12
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=`pwd`/vcpkg

iOS Swift Package

On iOS, you must pre-build the xcframework using the command:

./build.sh ios clean

Android

Prerequisites: See development.md, specifically setting up NDK 29.0.14206865 to match CI.

The project's build.gradle.kts includes a build task that automatically runs the script below selectively per architecture. It's also possible to run this manually:

./build.sh android clean

Valhalla Fork

This project uses our fork of valhalla at https://github.com/Rallista/valhalla as a submodule. If a feature is missing, please open an issue or PR on that repository to upgrade it to valhalla's latest version.

References

• Valhalla https://github.com/valhalla/valhalla
• Swift Package Manager C++ (for fun - this repo takes the old approach) https://www.swift.org/documentation/articles/wrapping-c-cpp-library-in-swift.html