GraphHopper is a fast and memory-efficient routing engine released under Apache License 2.0. It can be used as a Java library or standalone web server to calculate the distance, time, turn-by-turn instructions and many road attributes for a route between two or more points. Beyond this "A-to-B" routing it supports "snap to road", Isochrone calculation, mobile navigation and more. GraphHopper uses OpenStreetMap and GTFS data by default and it can import other data sources too.
This fork adds Overture Maps as a first-class data source,
imported into the same graph and encoded values as OSM. The reader is chosen from
datareader.file, so nothing else about the engine changes.
We have an open community and welcome everyone. Let us know your problems, use cases or just say hello. Please see our community guidelines.
All questions go to our forum where we also have subsections specially for developers, mobile usage, and our map matching component. You can also search Stackoverflow for answers.
Read through our contributing guide for information on topics like finding and fixing bugs and improving our documentation or translations! We also have good first issues to get started with contribution.
To get started you can try GraphHopper Maps, read through our documentation and install GraphHopper including the Maps UI locally.
- 11.x: documentation , web service jar , announcement
- unstable master: documentation
See the changelog file for Java API Changes.
Click to see older releases
- 10.x: documentation , web service jar , announcement
- 9.x: documentation , web service jar , announcement
- 8.x: documentation , web service jar , announcement
- 7.x: documentation , web service jar , announcement
- 6.x: documentation , web service jar , announcement
- 5.x: documentation , web service jar , announcement
- 4.x: documentation , web service jar , announcement
- 3.x: documentation , web service jar , announcement
- 2.x: documentation , web service jar , announcement
- 1.0: documentation , web service jar , Android APK , announcement
- 0.13.0: documentation , web service jar , Android APK , announcement
- 0.12.0: documentation , web service jar , Android APK , announcement
- 0.11.0: documentation , web service jar , Android APK , announcement
- 0.10.0: documentation , web service zip , Android APK , announcement
- 0.9.0: documentation , web service zip , Android APK , announcement
- 0.8.2: documentation , web service zip , Android APK , announcement
- 0.7.0: documentation , web service zip , Android APK , announcement
To install the GraphHopper Maps UI and the web service locally you need a JVM (>= Java 25) and do:
wget https://repo1.maven.org/maven2/com/graphhopper/graphhopper-web/11.0/graphhopper-web-11.0.jar \
https://raw.githubusercontent.com/graphhopper/graphhopper/11.x/config-example.yml \
http://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf
java -D"dw.graphhopper.datareader.file=berlin-latest.osm.pbf" -jar graphhopper*.jar server config-example.ymlAfter a while you see a log message with 'Server - Started', then go to http://localhost:8989/ and you'll see a map of Berlin. You should be able to right click on the map to create a route.
See the documentation that contains e.g. the elevation guide and the deployment guide.
The Docker images created by the community from the master branch can be found here
(currently daily). See the Dockerfile for more details.
The GraphHopper routing server uses GraphHopper Maps as web interface, which is also open source.
To see GraphHopper Maps in action go to graphhopper.com/maps/, which is an instance of GraphHopper Maps and available for free, via encrypted connections and from German servers - for a nice and private route planning experience!
The GraphHopper Directions API is our commercial offering that provides multiple APIs based on this open source routing engine: the Routing API, the Matrix API, the Isochrone API and the Map Matching API.
It also provides the Route Optimization API, which is based on our open source jsprit project and uses the fast Matrix API behind the scenes.
The address search is based on the open source photon project, which is supported by GraphHopper GmbH.
There is the /navigate web service that can be consumed by the Maplibre Navigation SDK or the ferrostar SDK.
Offline routing is no longer officially supported but should still work as Android supports most of Java. See version 1.0 with the Android demo and also see this pull request of the iOS fork including a demo for iOS.
Use isochrones to calculate and visualize the reachable area for a certain travel mode.
You can try the debug user interface at http://localhost:8989/maps/isochrone/ to see the /isochrone and /spt endpoint in action.
There is the map matching subproject to snap GPX traces to the road.
GraphHopper supports several routing algorithms, such as
Dijkstra and
A* and its bidirectional variants.
Furthermore, it allows you to use
Contraction Hierarchies (CH)
very easily. We call this speed mode; without this CH preparation, we call it flexible mode.
The speed mode comes with very fast and lightweight (less RAM) responses and it does not use heuristics. However, only predefined vehicle profiles are possible and this additional CH preparation is time and resource consuming.
Then there is the hybrid mode which also requires more time and memory for the preparation, but it is much more flexible regarding changing properties per request or e.g. integrating traffic data. Furthermore, this hybrid mode is slower than the speed mode, but it is an order of magnitude faster than the flexible mode and uses less RAM for one request.
If the preparations exist you can switch between all modes at request time.
Read more about the technical details here.
We chose the Apache License to make it easy for you to embed GraphHopper in your products, even closed source. We suggest that you contribute back your changes, as GraphHopper evolves fast.
OpenStreetMap is directly supported by GraphHopper. Without the amazing data from OpenStreetMap, GraphHopper wouldn't be possible at all. Other map data will need a custom import procedure, see e.g. Ordnance Survey, Shapefile like ESRI or Navteq.
This fork adds Overture Maps as a second data source, so the note above about custom import procedures does not apply to Overture: it is imported directly, into the same graph and the same encoded values that OSM uses.
Which reader runs is decided by graphhopper.datareader.file; there is no setting to choose one.
| Source | Path format | Reader | Notes |
|---|---|---|---|
| OpenStreetMap (local) | *.pbf, *.osm, *.xml, *.bz2, *.bzip2, *.gz, *.zip |
OSMReader |
The standard GraphHopper import path, unchanged |
| Overture (local) | *.parquet, *.geojson |
OvertureReader |
Parquet is streamed, so prefer it for large extracts |
| Overture (S3) | s3://bucket/key.parquet |
OvertureReader |
Parquet only; GeoJSON over S3 is deliberately rejected |
Overture imports need their own encoded values and custom models, which is why the fork ships
config-overture-osm.yml alongside upstream's config-example.yml. Use it
for any Overture import:
java -D"dw.graphhopper.datareader.file=europe.parquet" \
-jar web/target/graphhopper-web-*.jar server config-overture-osm.ymlAn S3 source works the same way. Credentials and region come from the standard AWS chain, and the client is created only when the import actually reads from S3:
java -D"dw.graphhopper.datareader.file=s3://my-bucket/overture/transportation.parquet" \
-jar web/target/graphhopper-web-*.jar server config-overture-osm.ymlOvertureSupport.configure does everything an Overture import needs: it installs the Overture
import registry, assembles the parser pipeline from whichever encoded values were created, and
resolves datareader.file to a local file or an S3 bucket and key. Call it before init, because
the registry has to be in place when the encoded values are built.
GraphHopper hopper = new GraphHopper();
hopper.setDataReaderInitializer(OvertureSupport.configure(hopper));
hopper.setDataFile("europe.parquet"); // or "s3://my-bucket/overture/transportation.parquet"
hopper.setGraphHopperLocation("graph-cache");
hopper.setProfiles(new Profile("car").setCustomModel(GHUtility.loadCustomModelFromJar("car.json")));
hopper.importOrLoad();To supply your own S3 client - a custom endpoint, for instance - wrap the initializer rather than building the reader from scratch, so it still gets its parser pipeline and source resolution:
DataReaderInitializer overture = OvertureSupport.configure(hopper);
hopper.setDataReaderInitializer(context ->
((OvertureReader) overture.initializeDataReader(context)).setS3Client(myS3Client));A runnable example lives in OvertureRoutingExample.java.
Overture's schema does not cover everything GraphHopper can encode. Values with no Overture source keep their defaults, and the import reports which ones, so the gap is visible rather than silent:
WARN OvertureParsers - Overture import cannot fill 10 encoded value(s): [bike_network,
bike_priority, bike_road_access, foot_network, foot_priority, foot_road_access, hike_rating,
mtb_rating, road_access, roundabout]. They keep their default value on every edge, which
affects any custom model reading them.
Note that a default is not "unknown" - an unwritten speed reads as a limit of zero - so a custom model that reads one of these will silently misbehave rather than fall back.
Because of that, the in-built custom models cannot all be used as-is: bike_overture.json,
foot_overture.json and bus_overture.json are Overture counterparts that leave out the clauses
which would read an unfilled value. car.json works unchanged.
Two further limits worth knowing:
- Ferries are imported and routable. Railways are not - they carry no access restrictions, so importing them would add track that every profile treats as open road.
- Turn restrictions (
prohibited_transitions) are extracted but not yet applied, soturn_costson an Overture profile only affects u-turns.
Implement DataReader, have a
DataReaderInitializer build it from the DataReaderContext it is given - the context carries the
graph, the encoded values and the configured source - and register it with
setDataReaderInitializer. The reader is responsible for filling the encoded values your profiles
read; anything it leaves alone keeps its storage default, which is rarely the same as "unknown".
OvertureSupport is the
smallest complete example of that wiring.
GraphHopper is written in Java and officially runs on Linux, Mac OS X and Windows.
Embed GraphHopper with OpenStreetMap support into your Java application via the following snippet:
<dependency>
<groupId>com.graphhopper</groupId>
<artifactId>graphhopper-core</artifactId>
<version>[LATEST-VERSION]</version>
</dependency>See our example application to get started fast.
You can customize GraphHopper with Java knowledge (with a high and low level API) and also without Java knowledge using the custom models.
With the web module, we provide code to query GraphHopper over HTTP and decrease bandwidth usage as much as possible. For that we use an efficient polyline encoding, the Ramer–Douglas–Peucker algorithm, and a simple GZIP servlet filter.
On the client side, we provide a Java and JavaScript client.
GraphHopper also runs on the Desktop in a Java application without internet access. For debugging purposes GraphHopper can produce vector tiles, i.e. a visualization of the road network in the browser (see #1572). Also a more low level Swing-based UI is provided via MiniGraphUI in the tools module, see some visualizations done with it here. A fast and production-ready map visualization for the Desktop can be implemented via mapsforge or mapsforge vtm.
- Works out of the box with OpenStreetMap (osm/xml and pbf) and can be adapted to custom data
- OpenStreetMap integration: stores and considers road type, speed limit, the surface, barriers, access restrictions, ferries, conditional access restrictions and more
- GraphHopper is fast. And with the so called "Contraction Hierarchies" it can be even faster (enabled by default).
- Memory efficient data structures, algorithms and the low and high level API is tuned towards ease of use and efficiency
- Pre-built routing profiles: car, bike, racing bike, mountain bike, foot, hike, truck, bus, motorcycle, ...
- Customization of these profiles are possible. Read about it here.
- Provides a powerful web API that exposes the data from OpenStreetMap and allows customizing the vehicle profiles per request. With JavaScript and Java clients.
- Provides map matching i.e. "snap to road".
- Supports time-dependent public transit routing and reading GTFS.
- Offers turn instructions in more than 45 languages. Contribute or improve here.
- Displays and takes into account elevation data.
- Supports alternative routes.
- Supports turn costs and restrictions.
- Offers country-specific routing via country rules.
- Allows customizing routing behavior using custom areas.
- Scales from small indoor-sized to world-wide-sized graphs.
- Finds nearest point on street e.g. to get elevation or 'snap to road' or being used as spatial index (see #1485).
- Calculates isochrones and shortest path trees.
- Shows the whole road network in the browser for debugging purposes ("vector tile support"), see #1572.
- Shows so called "path details" along a route like road_class or max_speed, see #1142 or the web documentation.
- Written in Java and simple to start for developers via Maven.