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. The README separates the open source engine from the commercial side by pointing at GraphHopper Maps and the project site, and 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. The README does not publish import timings or memory figures, so the honest answer is that you measure your own region before sizing a machine.

Algorithm choices are visible in the project topics: A*, Dijkstra, isochrones, map matching, public transportation. 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. The README does not include a worked request example, so 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) that depends on the core library. 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 topics list Android, but the README's current Get Started section routes mobile users through the documentation rather than a download link.

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. The README does not document rollback, so a failed import is a problem you solve with your own backup of the graph directory, not with a flag.

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.

Finally, the README does not publish capacity numbers. There is no statement about requests per second per core, or about how large an extract fits in how much heap. Anyone quoting such figures for GraphHopper is quoting their own deployment, not the project.

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: the README does not benchmark GraphHopper against OSRM or Valhalla, and neither should you 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-09-21, so the project is being worked on. Release cadence is visible in the README's release list: 11.0 in October 2025, 10.2 in January 2025, 10.0 in November 2024. 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. Note also that the README distinguishes the open source engine from the commercial GraphHopper offering, so check which one you are actually using before assuming the Apache terms cover everything.

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, since the README points to a hosted offering separately from the open source engine. 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