Valhalla routing engine: a practical guide for developers

Routing is a cornerstone of any location-based application. It offers a way to compute directions, understand distances between points, and visualize travel scenarios on maps. The Valhalla routing engine, an open-source project, allows developers to implement highly customizable routing solutions that can adapt to a variety of use cases. This guide provides an in-depth analysis of how Valhalla works, its capabilities such as the directions matrix and isochrone routing, and practical examples for leveraging it in your projects.

Overview of Valhalla

Valhalla, developed by Mapzen and now maintained by an open-source community, is designed to provide detailed routing and navigation solutions. Key features include its ability to produce turn-by-turn directions, compute service matrices, handle multiple modes of transportation, and support time-dependent routing. Built using C++ and with a clear focus on using OpenStreetMap (OSM) data, Valhalla emphasizes performance and flexibility.

Architecture and data sources

Valhalla is built on a modular architecture that allows for easy integration of different components. The main modules include:

1. Routing: The core component responsible for finding paths between locations.
2. Location: Handles coordinates and geospatial queries.
3. Transit: Manages public transit routing.
4. Search: Provides location-based searches and supports geocoding.
5. Slide: Facilitates isochrone calculations.

Valhalla relies heavily on OpenStreetMap (OSM) data, which offers detailed, crowd-sourced mapping information including road networks, public transit routes, and various geographical features.

Directions and routing

Valhalla offers various routing functionalities, enabling detailed navigation solutions. The basic routing request obtains turn-by-turn directions between two points, returning detailed instructions that can be rendered in applications.

Turn-by-turn routing with Valhalla

The simplest way to use Valhalla for turn-by-turn directions is via HTTP API calls. Here’s a sample request:

curl -X GET "https://api.mapsi.dev/route?start=37.7749,-122.4194&end=37.7849,-122.4294&costing=auto&format=json&instructions=true&units=miles"

This request calculates a route for a car from point A (latitude 37.7749, longitude -122.4194) to point B (latitude 37.7849, longitude -122.4294). The instructions=true parameter ensures that detailed turn-by-turn navigation instructions are returned.

A typical response looks like this:

{
  "routes": [
    {
      "legs": [
        {
          "maneuvers": [
            {
              "instruction": "Head north on Main St.",
              "distance": 300.0,
              "time": 60
            },
            {
              "instruction": "Turn right onto 1st St.",
              "distance": 150.0,
              "time": 30
            }
          ]
        }
      ]
    }
  ]
}

This response provides detailed guidance, allowing developers to integrate turn-by-turn navigation effectively into their applications.

Directions matrix

Valhalla supports the calculation of direction matrices, which is essential when you need to evaluate multiple routes between many origins and destinations. This is especially useful for logistics or ride-sharing services where quick evaluations of routing options can save time and costs.

To generate a directions matrix, you will use a similar API request but specify multiple start and end points. The structure may look like this:

curl -X POST "https://api.mapsi.dev/matrix" \
     -H "Content-Type: application/json" \
     -d '{
           "sources": [[37.7749, -122.4194], [37.7849, -122.4294]],
           "targets": [[37.7949, -122.4394], [37.8049, -122.4494]],
           "costing": "auto"
         }'

The response will contain the time and distances for every combination of origins and destinations. This feature is particularly beneficial for logistics providers, as it allows them to compute optimal routes and schedules efficiently.

Isochrone routing

Isochrone analysis is another powerful feature facilitated by Valhalla. It enables developers to visualize areas reachable within a specified time from a starting point. This is useful for determining service areas or understanding the impact of travel time on accessibility.

To calculate isochrones, you can issue a POST request like this:

curl -X POST "https://api.mapsi.dev/isochrone" \
     -H "Content-Type: application/json" \
     -d '{
           "locations": [[37.7749, -122.4194]],
           "range": [600, 1200, 1800],
           "attributes": ["area"]
         }'

This request would return the areas that can be reached within 10, 20, and 30 minutes from the start location. The response typically includes polygons representing the different travel times, which can be rendered on a map.

Comparison with other routing engines

To give context for Valhalla, here's a comparison with two other popular routing engines: Mapbox and OSRM (Open Source Routing Machine).

Feature	Valhalla	Mapbox	OSRM
Data Source	OpenStreetMap (OSM)	OpenStreetMap (OSM)	OpenStreetMap (OSM)
Modes of Transport	Multi-modal	Car, bicycle, pedestrian	Car, bicycle
Directions Matrix	Yes	Limited	Not available
Isochrone Routing	Yes	Limited	Not available
Open-source	Yes	No	Yes
Complexity of Setup	Moderate	Easy	Moderate

Closing thoughts

Valhalla provides robust functionalities suitable for a wide range of routing applications. With features like turn-by-turn navigation, direction matrices, and isochrone analysis, it supports the creation of detailed and responsive applications that can meet user needs effectively. Next, explore the Valhalla documentation or integrate some of these examples into your projects for real-world insights into its capabilities.

FAQ

curl "https://api.mapsi.dev/geocode?q=Berlin&key=YOUR_KEY"