GraphHopper: a Java routing engine for OpenStreetMap

What GraphHopper solves, and who it is actually for

GraphHopper is an open source routing engine for OpenStreetMap, released under Apache License 2.0. The README describes two ways to consume it: as a Java library, or as a standalone web server. In both cases the engine calculates distance, time, turn-by-turn instructions and many road attributes for a route between two or more points. It uses OpenStreetMap and GTFS data by default, along with elevation data, and can import other data sources.

The audience is narrower than the download numbers suggest. If you are building a logistics dashboard, a fleet tool, a fitness application or an internal travel-time service, and you want the routing graph on your own machines, GraphHopper is aimed at you. If you want to call an endpoint and never think about data imports, it is not. Questions go to a forum rather than a support contract.

The feature list beyond A-to-B routing matters here. The README names snap-to-road, isochrone calculation and mobile navigation. Snap-to-road means you can take a noisy GPS trace and match it to the road network. Isochrones answer how far you can travel within a time budget, which is a different query shape from shortest path. Those two features, more than plain routing, are what often decide whether a team picks this project.

The architecture: import once, query many times

GraphHopper is a graph engine, and the repository layout reflects that split. The core module holds the routing logic. The web module and web-bundle module wrap it as a server. Separate top-level modules exist for GTFS reading, map matching, navigation and a Java client. That separation is the data flow: you import an OpenStreetMap extract into a graph, the graph is stored on disk, and queries run against the prepared graph rather than against raw OSM XML.

This is the same broad shape as other self-hosted routing engines, and it has the same consequence. Import time and disk usage scale with the extract, not with query volume. Once the graph is built, queries are cheap and stateless. Measure your own region before sizing a machine.

The CHANGELOG file is described as covering Java API changes, which tells you the library surface is versioned deliberately. That matters if you embed GraphHopper in a larger Java service, because an upgrade can move method signatures. The README points readers to the changelog for exactly that reason.

Installing GraphHopper and running a first route

The README's Get Started section does not walk through a shell session. It links to the documentation and to the web service jar for the current release line. The 11.x documentation is the reference to follow, and the web service jar is published on Maven Central. The repository ships a config-example.yml at the top level, which is the file to copy and edit rather than writing one from scratch. The README does not spell out every key in that file, so treat it as the source of truth for the version you run.

Once the server is running, requests go to the HTTP API, and the repository's client-hc module is a Java HTTP client for it while web-api defines the request and response objects. Read the 11.x documentation for the exact endpoint and parameter names before writing client code.

For embedding rather than serving, the example directory contains a Maven project (example/pom.xml). The README does not reproduce that build file in full, so read it in the repository before adapting it. The Android path exists too: older releases published an APK, and the README links a mobile navigation section, but the current release lines list no APK.

Where GraphHopper is the wrong tool

The clearest limitation is operational, not algorithmic. GraphHopper is a data pipeline plus a server. You own the OpenStreetMap extract, the import step, the disk, the memory and the refresh cycle. If your region changes and you want updated roads, you re-import.

A second boundary is language. The engine is Java. The README frames it as a Java library or a standalone web server, and the modules are Maven projects. If your stack is Python or Go, you are integrating over HTTP rather than linking in-process, and you inherit the server's lifecycle. That is fine for many teams and awkward for others.

Third, the project is a routing engine, not a geocoder. It answers routes between coordinates. Turning an address into a coordinate is a different service, and nothing in the README suggests GraphHopper replaces one. Teams that conflate the two end up surprised at the first user-entered address.

GraphHopper compared with OSRM and Valhalla

The three names that come up together are GraphHopper, OSRM and Valhalla, and the difference that matters most is the integration surface. OSRM is built around a C++ pipeline and a Lua-based profile system, and it is normally deployed as a service. Valhalla is also a service-first engine, with its own tiling and costing model. GraphHopper's distinguishing offer, stated plainly in the README, is that it can be used as a Java library as well as a standalone web server. If you are writing a JVM application and want routing in the same process, that is a real difference in approach, not a marketing one.

The second difference is the feature set around the core. GraphHopper ships a map-matching module and an isochrone module as part of the same repository, and the README lists both as first-class capabilities. With OSRM, map matching is available but the surrounding analysis features are assembled differently. With Valhalla, isochrones are a documented endpoint. None of these is a clean win; they are different packaging choices.

The third difference is licensing posture. GraphHopper is Apache-2.0, which is permissive and business-friendly. That is a genuine factor for teams that embed a routing engine inside a product and do not want copyleft obligations. Check the LICENSE.txt and NOTICE.md in the repository for the exact terms rather than relying on the licence identifier alone.

One caveat on comparisons: do not take any third-party benchmark at face value without reproducing it on your own extract and hardware.

Maintenance, upgrades and licence cost

The repository is not archived and the last push was on 2026-11-02, so the project is being worked on. Release cadence is visible in the README's release list: 11.1 in September 2026, 11.0 in October 2025, 10.2 in January 2025. That is roughly one minor line per year with point releases between, which is a comfortable pace for a routing engine but not a fast one. Plan upgrades around that rhythm rather than expecting weekly movement.

The upgrade cost is concentrated in the Java API. The README explicitly points to the CHANGELOG.md file for Java API changes, and that file exists at the top level of the repository. If you embed the core library, read the changelog before moving a major version. If you run the web service jar, the HTTP surface is what you depend on, and the web-api module defines it.

On licensing: the project is released under Apache License 2.0, which permits commercial use and modification. The repository carries LICENSE.txt and NOTICE.md, and a NOTICE file usually means there are attribution obligations to preserve. I am not giving legal advice; if you redistribute GraphHopper inside a product, have your own counsel read those two files.

Editorial conclusion

Adopt GraphHopper when you need routing you control: a Java service that imports OpenStreetMap and GTFS and answers A-to-B, map-matching and isochrone queries on your own hardware. Skip it if you want a managed endpoint with an API key and no data pipeline. Before committing, verify the 11.x documentation against your data region, confirm the memory and disk your extract needs, and check whether your profile requires elevation data, because the README lists elevation as part of the default setup.

Frequently asked questions

Official sources

1. graphhopper/graphhopper on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases