Host Your Own Worldwide Route Calculator With GraphHopper

{
 "priority": [{
   "if": "road_class == PRIMARY",
   "multiply_by": 0.1
 }, {
   "if": "max_speed >= 50",
   "multiply_by": 0.1
 }]
}

The syntax is explained in detail here. Note that the best way to tweak your custom model is to use the interactive custom model input box of the GraphHopper Maps UI. Once you are happy with your custom model you can copy it to a file named bike.json and reference it in the bike profile of your config.yml file like this:

graphhopper:
  ...
  profiles:
    - name: bike
      vehicle: bike
      weighting: custom
      custom_model_file: bike.json

This way the customization will become the default for queries using the bike profile and still you can adjust it further from the client side. Note that when you make changes to your routing profiles you need to run the import again. So either delete the berlin-gh folder or change the graph.location and use another folder.

graphhopper:
  # ... same as above  
  profiles_lm:
    - profile: bike
    - profile: foot

  prepare.lm.threads: 2

There is one important restriction for LM when you want to change the custom model at runtime: The weights used for each road can only be increased, but never decreased. So for example increasing speeds or priorities is prohibited but they can be decreased at will. An easy workaround is using large speeds in your server profile, but keep in mind that the routing queries will be the faster the closer the adjusted speeds are to the ones that were used when running the LM preparation.

Of course you can add LM and CH profiles for the same profile at the same time. When CH is available it will be the default, but you can still use the ch.disable=true parameter to make use of LM. And if LM is available you can disable it using lm.disable=true to gain full flexibility.

Scaling Up

Until now you learned how GraphHopper deals with a small OSM data set for the city of Berlin. However, from the very beginning it was one of GraphHopper’s primary goals to handle the full planet file, which nowadays contains over 60GB compressed geographic information of the world. Handling this amount of data in a fast and memory-efficient way is a real challenge and one thing where GraphHopper shines. By the way, this part is even utilized in planetiler – the (fastest?) tool to create planet-scale vector tiles from OSM data.

So let’s talk about how to use GraphHopper for larger maps and what to do in a few common situations.

Continental sized maps or even the full planet file require a lot more memory and initial processing time. Both are roughly proportional to the size of the map, which can either be approximated directly by the size of the OSM file or expressed by the number of ‘edges’ (connections between road junctions) of the GraphHopper graph. Take a look at the following table, created using the above configuration (without CH):

The first thing you need to do when using larger maps is increasing Java’s heap size. This is done using the Xmx flag, e.g.
java -Xmx4g -jar graphhopper-web-[version].jar import config.yml
will set the heap size to 4GB. If you set this value too small the import can become very slow or even fail due to insufficient heap memory. In this case you will usually an exception thrown by the JVM, but be aware that in some cases also the operating system might kill the process. How large the heap space needs to be depends on the size of the map and a few more choices you can make.

Also note that here we used the import command rather than the server command as we did previously. This is always recommended when running imports for larger maps. Compared to the server command the import command does not start the server when the import is complete, but in turn it is able to free up memory that is no longer needed during the import process. When the import is done you can just use the server command with the same configuration to start the server.

For lowest possible latency of routing requests you should also enable a low latency garbage collector (GC) for the JVM (Note that for the import command this is not recommended). In our experience a low latency GC is important not only for very large heaps but already when the Xmx setting is above 5GB. We use ZGC in production since several years (enable it via -XX:+UseZGC) and another good choice can be Shenandoah GC (-XX:+UseShenandoahGC).

For an updated deployment guide please see our documentation.

Worldwide Example with CH

At the time of this writing (May 2022) and with the short configuration from the top and this change:

graphhopper:
  ...
  profiles_ch:
    - profile: car
    - profile: bike

  prepare.ch.threads: 1 # more threads require even more memory

you can start the import with:

java -Xmx120g -Xms120g -jar graphhopper-web-[version].jar import config.yml

Without the option -Xms the JVM always tries to reduce its heap size (to release it to the operating system) which might result in a busier garbage collector that you should avoid.

Likely, these memory requirements sound extraordinary to you. Please keep in mind that in this case GraphHopper holds the road network of the entire world in memory plus the “speed up” data. Compared to other open source routing engines with the same fast query speed, the memory requirements of GraphHopper are still lower as you can run one instance with multiple profiles (the road network data is shared). Furthermore, GraphHopper still offers you “per-request” flexibility as you can deactivate the CH algorithm for each individual requests. See the next section.

Worldwide Example for LM

At the time of this writing (May 2022) and with the short configuration from the top and this change:

graphhopper:
  ...
  profiles_lm:
    - profile: car
    - profile: bike

  prepare.lm.threads: 1

you can start the import command:

java -Xmx60g -Xms60g -jar graphhopper-web-[version].jar import config.yml

As previously explained, LM requires less time than CH when turn_costs are enabled and still allows for flexible routing queries.

Worldwide Examples

Memory Tuning

The CH and LM preparations are meant to speed up the routing queries at the cost of a longer import time and more memory usage. If your hardware does not provide enough memory the easiest thing you can do is just not use these speed-up techniques at all. Even without these GraphHopper is still fast, especially for shorter routes. In this case you might want to enforce a maximum query distance to prevent long running routing requests and make sure you do not run out of memory at query time. This is done using the setting
routing.non_ch.max_waypoint_distance: 1000000
which limits the maximum query distance to 1000km for example. You can also have a look into routing.max_visited_nodes. There are a few more ways to reduce the memory needed to start the GraphHopper server:

Separate routing profiles

GraphHopper is very efficient when it comes to using the same road network for multiple routing profiles. For example if you use different profiles for various types of cars, trucks and motorcycles there will be only a small increase of the required memory, because a lot of data will be shared between these different profiles. However, there are certain roads that aren’t used by certain vehicles at all. For example the foot profile might never use motorways, or a car profile might never use foot- or cycleways. GraphHopper ignores unused roads entirely, so you can reduce the size of the graph by separating profiles that use different sets of road types. Especially separating motorized vehicles from non-motorized ones (like bike and foot) can make a big difference. It won’t reduce the overall memory requirement, but you might be able to use two smaller machines instead of a single big one.

Memory mapped files

You can also configure GraphHopper such that it does not load the imported graph into memory at all. This way you can drastically reduce the memory requirement, but the import will be much slower. For example importing the planet file will take about three days rather than about 1.5 hours. To enable memory mapping you need to set
graph.dataaccess.default_type: MMAP
in the config file. When using MMAP you should try to use a maximum of 50% of the physical memory for Xmx. This way there is enough heap space for objects created during the import and the operating system has enough memory for the memory mapped graph data.

Another advantage of using MMAP compared to RAM_STORE is that it speeds up the server startup time as less data is loaded initially. The query speed will be slower, though. If you want to still preload the data into memory you can since v5.0.

Run the import on separate hardware

Importing OSM data requires more memory than actually running the server using the imported data. Therefore you can use a larger machine with more memory to run the import command and then copy the GraphHopper folder to one or more smaller machines where you start the server using the server command.

Note that you can also use a combination of MMAP and RAM_STORE. If you use different hardware for the import and the routing service it can help to use MMAP only for the routing service. This way you can benefit from a fast import and smaller memory requirements on your routing server.