Repository files navigation

 ██▒   █▓ ▄▄▄       ██▓     ██░ ██  ▄▄▄       ██▓     ██▓    ▄▄▄▓██░   █▒▒████▄    ▓██▒    ▓██░ ██▒▒████▄    ▓██▒    ▓██▒   ▒████▄ ▓██  █▒░▒██  ▀█▄  ▒██░    ▒██▀▀██░▒██  ▀█▄  ▒██░    ▒██░   ▒██  ▀█▄  ▒██ █░░░██▄▄▄▄██ ▒██░    ░▓█ ░██ ░██▄▄▄▄██ ▒██░    ▒██░   ░██▄▄▄▄██   ▒▀█░   ▓█   ▓██▒░██████▒░▓█▒░██▓ ▓█   ▓██▒░██████▒░██████▒▓█   ▓██▒   ░ ▐░   ▒▒   ▓▒█░░ ▒░▓  ░ ▒ ░░▒░▒ ▒▒   ▓▒█░░ ▒░▓  ░░ ▒░▓  ░▒▒   ▓▒█░   ░ ░░    ▒   ▒▒ ░░ ░ ▒  ░ ▒ ░▒░ ░  ▒   ▒▒ ░░ ░ ▒  ░░ ░ ▒  ░ ▒   ▒▒ ░     ░░    ░   ▒     ░ ░    ░  ░░ ░  ░   ▒     ░ ░     ░ ░    ░   ▒      ░        ░  ░    ░  ░ ░  ░  ░      ░  ░    ░  ░    ░  ░     ░  ░     ░

Linux	macOS & Windows	Code Coverage

Valhalla, and all of the projects under the Valhalla organization, use theMIT License. Avatar/logo byJordan.

OpenStreetMap data in the./test/data is licensed underODbL andcopyrighted by OSM contributors. Additional information on licenses and other requirements concerning the data sources most frequently used by Valhalla can be found inthe docs.

There are several key features that we hope can differentiate the Valhalla project from other routing and network analysis engines. They are:

• Open source software, on open source data with a very liberal license. Should allow for transparency in development, encourage contribution and community input, and foster use in other projects.
• Tiled hierarchical data structure. Should allow users to have a small memory footprint on memory constrained devices, enable offline routing, provide a means for regional extracts and partial updates.
• Dynamic, runtime costing of edges and vertices within the graph via a plugin architecture. Should allow for customization and alternate route generation.
• C++ based API. Should allow for cross compilation of the various pieces to enable routing on offline portable devices.
• A plugin based narrative and manoeuvre generation architecture. Should allow for generation that is customized either to the administrative area or to the target locale.
• Multi-modal and time-based routes. Should allow for mixing auto, pedestrian, bike and public transportation in the same route or setting a time by which one must arrive at a location.

FOSSGIS e.V. hosts a demo server which is open to the public and includes a full planet graph with anopen-source web app onhttps://valhalla.openstreetmap.de. The HTTP API is accessible on a slightly different subdomain, e.g.https://valhalla1.openstreetmap.de/isochrone. Usage of the demo server follows the usual fair-usage policy as OSRM & Nominatim demo servers (somewhat enforced byrate limits).

Valhalla is fully functional on many Linux and Mac OS distributions, and is also used on iOS and Android devices.

For Windows, not all functionality is fully supported yet. Building the Valhalla library works flawlessly, as well as the following application modules:

• TOOLS: utilities to query and benchmark various components
• DATA_TOOLS: utilities to build input data and handle transit
• PYTHON_BINDINGS: use all actions (route, isochrones, matrix etc) via the Valhalla Python library (needs a full (i.e. development) Python distribution in thePATH)

The Valhalla organization is comprised of several library modules each responsible for a different function. The layout of the various modules is as follows:

• Midgard - Basic geographic and geometric algorithms for use in the various other projects.
• Baldr - The base data structures for accessing and caching tiled route data.
• Sif - Library used in costing of graph nodes and edges. This can be used as input toloki andthor.
• Skadi - Library and service for accessing elevation data. This can be used as input tomjolnir or as a standalone service.
• Mjolnir - Tools for turning open data into Valhalla graph tiles.
• Loki - Library used to search graph tiles and correlate input locations to an entity within a tile. This correlated entity (edge or vertex) can be used as input tothor.
• Meili - Library used to for map-matching.
• Thor - Library used to generate a path through the graph tile hierarchy. This path and attribution along the path can be used as input toodin.
• Odin - Library used to generate manoeuvres and narrative based on a path. This set of directions information can be used as input totyr.
• Tyr - Service used to handle http requests for a route communicating with all of the other valhalla APIs. The service will format output fromodin and support json (and eventually protocol buffer) output.
• Tools - A set command line tools that exercise bits of functionality from the library components above and provide the basis for quality testing and performance benchmarking.
• Demos - A set of demos which allows interacting with the service and APIs.

Documentation is stored in thedocs/ folder in this GitHub repository. It can be viewed atvalhalla.github.io/valhalla.

For more information on binaries, seeCommand Line Tools section below and thedocs.

If you want to build Valhalla from source, follow thedocumentation.

To run Valhalla locally or your own server, we recommend using our Docker image. Checkout our docker image here:https://github.com/orgs/valhalla/packages. Also, there's acommunity Docker image with more "magic" than the native one.

We publish our (very) high-level Python bindings to PyPI:

• pyvalhalla: follows Github releases
• pyvalhalla-weekly: follows Github master branch

The Python packages don't only contain the Python bindings, they also provide access to the C++ executables, e.g. in the form ofpython -m valhalla valhalla_build_tiles -h. For more details, see thePython README.

To install the native C++ executables one doesn't even need to have root permissions or even have Python installed. Simply download the desired wheel fromPyPI, extract it with e.g.unzip and run the includedvalhalla/bin/<binary> directly.

We ❤️ contributions to Valhalla. They could be non-technical, e.g. translations into other languages viaTransifex or documentation improvements, or technical ones like bug fixes or feature implementations. It's important to open an issue before setting out to work on a PR.

Ideally, get familiar with ourContribution guidelines first.

Valhalla includes several microbenchmarks which you can build and run using:

make benchmarksmake run-benchmarks

They are enabled by the-DENABLE_BENCHMARKS=On CMake flag and are currently only available forLinux and MacOS.

If you can't (e.g. Windows Server) or don't want to have the full-fledged HTTP API running, you can have the (almost) exact same behavior with the 'valhalla_service' executable in so-called "one-shot" mode. It's simple, just pass the config file, the action (route, isochrone, matrix etc) and the stringified JSON request (or alternatively a file containing the request to circumvent shell command length issues):

valhalla_service valhalla.json isochrone '{"locations":[{"lat":42.552448,"lon":1.564865}],"costing":"auto","contours":[{"time":10,"color":"ff0000"}], "show_locations":true}'# Alternatively you can pass a file with the same contentsvalhalla_service valhalla.json isochrone isochrone_request.txt

It's important to note that all Valhalla logs for one-shot mode are piped tostderr while the actual JSON response will be instdout. To completely silence the logs, passtype: "" tomidgard.logging in the config file.

• Batch Run_Route

The following projects are open-source and built with the intention to make it easier to use Valhalla and its features:

• OpenStreetMapSpeeds: A project conflating open GPS data to improve Valhalla's speed classification. The current JSON is from early 2022 and can be downloadedhere and used by setting the path in themjolnir.default_speeds_config config option.
• docker-valhalla: An easy-to-use, relatively magical Docker image for Valhalla, which only requires setting a few environment variables indocker-compose.yml to get a full-featured Valhalla instance.
• valhalla-operator: A k8s operator to deploy and manage Valhalla.
• valhalla-app: A React based web app for Valhalla, poweringhttps://valhalla.openstreetmap.de/.
• valhalla-qgis-plugin: A QGIS plugin for Valhalla, also available in theofficial QGIS plugin store.Note, it's almost deprecated and will be replaced with a much superior alternative.
• routingpy: A Python client for most open-source routing engines, including Valhalla, with a common interface for all engines. Available onPyPI.
• routingjs: A TypeScript client for most open-source routing engines, including Valhalla, with a common interface for all engines. Available as engine-specific packages onnpm.
• Valhalla_jll.jl: Valhalla binaries shipped for Julia.
• valhalla-go: Valhalla Golang bindings via cgo