1. Sign up for GraphHopper
2. Create an API key

Each API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials.

You can also try all API parts without registration in our API explorer.

To speed up development and make coding easier, we offer a JavaScript client and a Java client.

Optimize Response Speed

1. Reuse SSL/TLS sessions

   You should utilize the SSL session to speed up responses after the initial response or use a library that does this. E.g. for Java the OkHttp library automatically reuses SSL/TLS sessions and also the browser takes care of this automatically. For python you can use the requests library: first you create a session (session = requests.Session()) and then do requests only with this session instead of directly using "requests".

2. Bandwidth reduction

   If you create your own client, make sure it supports http/2 and gzipped responses for best speed. If you use the Matrix, the Route Optimization API or the Cluster API and want to solve large problems, we recommend you to reduce bandwidth by compressing your POST request and specifying the header as follows: Content-Encoding: gzip. This will also avoid the HTTP 413 error "Request Entity Too Large".

If you have problems or questions, please read the following information:

• FAQ
• Public forum
• Contact us
• GraphHopper Status Page

To stay informed about the latest developments, you can

• follow us on twitter,
• read our blog,
• sign up for our newsletter or
• our forum.

The default data source is OpenStreetMap and as an alternative we have also integrated TomTom.

Geographical Coverage

OpenStreetMap covers the whole world. If you want to see for yourself if we can provide data suitable for your region, please visit GraphHopper Maps. You can edit and modify OpenStreetMap data if you find that important information is missing, e.g. a weight limit for a bridge. Here is a beginner's guide that shows how to add data. If you have edited data, we usually consider your data after 1 week at the latest.

Standard Routing Profiles

The Routing, Matrix and Route Optimization APIs support the following profiles. But also see the section about customized profiles below the table.

Name	Description	Restrictions	Icon
car	Car mode	car access, weight=2500kg, width=2m, height=2m
car_avoid_ferry	Car mode	like car that heavily penalizes ferries
car_avoid_motorway	Car mode	like car that heavily penalizes motorways
car_avoid_toll	Car mode	like car that heavily penalizes tolls
small_truck	Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily	height=2.7m, width=2+0.28m, length=5.5m, weight=2080+1400 kg
truck	Truck like a MAN or Mercedes-Benz Actros	height=3.7m, width=2.6+0.34m, length=12m, weight=13000+13000 kg, hgv=yes, 3 Axes
scooter	Moped mode	Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h. weight=300kg, width=1m, height=2m
foot	Pedestrian or walking without dangerous SAC-scales	foot access
hike	Pedestrian or walking with priority for more beautiful hiking tours and potentially a bit longer than foot. Walking duration is influenced by elevation differences.	foot access
bike	Trekking bike avoiding hills	bike access
mtb	Mountainbike	bike access
racingbike	Bike preferring roads	bike access

Please note:

• the free package supports only the routing profiles car, bike or foot
• up to 3 different routing profiles can be used in a single request towards the Route Optimization API. The number of vehicles is unaffected and depends on your subscription.
• we offer custom routing profiles with different properties, different speed profiles or different access options. To find out more about custom profiles, see the documentation and contact us.
• a sophisticated motorcycle profile is available up on request. It is powered by the Kurviger Routing API and favors curves and slopes while avoiding cities and highways.

Customized Routing Profiles

You can also adjust the speeds, access options and much more by using customized routing profiles. We offer this for the Routing API (see the section about Custom Models). For interested customers we offer the Profiles API that can be used for matrix calculations and route optimiztion as well.

If you want to include traffic, you can purchase the TomTom Add-on. This Add-on only uses TomTom's road network and historical traffic information. Live traffic is not yet considered. If you are interested to learn how we consider traffic information, we recommend that you read this article.

Please note the following:

• Currently we only offer this for our Route Optimization API. Contact us if you would like to use it for the Matrix or Routing API.
• In addition to our terms, you need to accept TomTom's End User License Aggreement.
• We do not use TomTom's web services. We only use their data with our software.

Contact us if you want to buy this TomTom add-on.

Geographical Coverage

We offer

• Europe including Russia
• North, Central and South America
• Saudi Arabia and United Arab Emirates
• South Africa
• Southeast Asia
• Australia

Supported Vehicle Profiles

Name	Description	Restrictions	Icon
car	Car mode	car access
small_truck	Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily	height=2.7m, width=2+0.28m, length=5.5m, weight=2080+1400 kg

A custom model allows you to modify the default routing behavior of a vehicle profile by specifying a set of rules in JSON language. There are three JSON properties to change a profile: priority, speed and distance_influence that are described in great detail in the next sections and you can get a quick overview in this example-driven blog post.

But first we will give an introductory example for each of these JSON properties. Let's start with speed:

{
  "speed": [{
    "if": "road_class == MOTORWAY",
    "limit_to": "90"
  }]
}

As you might have already guessed this limits the speed on motorways to 90km/h. Changing the speed will of course change the travel time, but at the same time this makes other road classes more likely as well, so you can use this model to avoid motorways.

You can immediately try this out in the Browser on GraphHopper Maps. GraphHopper Maps offers an interactive text editor to comfortably enter custom models. You can open it by pressing the "custom" button. It will check the syntax of your custom model and mark errors in red. You can press Ctrl+Space or Alt+Enter to retrieve auto-complete suggestions. Pressing Ctrl+Enter will send a routing request for the custom model you entered. To disable the custom model you click the "custom" button again.

In the second example we show how to avoid certain road classes without changing the travel time:

{
  "priority": [{
    "if": "road_class == LIVING_STREET || road_class == RESIDENTIAL || road_class == UNCLASSIFIED",
    "multiply_by": "0.1"
  }]
}

This example avoids certain smaller streets. View it in GraphHopper Maps.

The third example shows how to prefer shortest paths:

{
  "distance_influence": 200
}

View this example in GraphHopper Maps.

There is a fourth JSON property areas that allows you to define areas that can then be used in the if or else_if conditions for speed and priority. Please read more about this and the other properties below and try some examples in GraphHopper Maps with the help of this blog post.

When using custom models you do not need to define rules that specify a speed for every road segment, but rather GraphHopper assumes a default speed. All you need to do is adjust this default speed to your use-case as you will always use the custom model in conjunction with a routing profile which is used to determine the default speed.

The custom model is a JSON object and the first property we will learn about here is the speed property. The speed property's value is a list of conditional statements that modify the default speed. Every such statement consists of a condition and an operation. The different statements are applied to the default speed from top to bottom, i.e. statements that come later in the list are applied to the resulting value of previous operations. Each statement is only executed if the corresponding condition applies for the current road segment. This will become more clear in the following examples.

Currently the custom model language supports two operators:

• multiply_by multiplies the speed value with a given number
• limit_to limits the speed value to a given number

if statements and the multiply_by operation

Let's start with a simple example using multiply_by:

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    }
  ]
}

This custom model reduces the speed of every road segment for which the road_class attribute is MOTORWAY to fifty percent of the default speed (the default speed is multiplied by 0.5). Again, the default speed is the speed that GraphHopper would normally use for the profile's vehicle. Note the if clause which means that the operation (multiply_by) is only applied if the condition road_class == MOTORWAY is fulfilled for the road segment under consideration. The == indicates equality, i.e. the condition reads "the road_class equals MOTORWAY". If you're a bit familiar with programming note that the condition (the value of the if key) is just a boolean condition in Java language (other programming languages like C or JavaScript are very similar in this regard). A more complex condition could look like this: road_class == PRIMARY || road_class == TERTIARY which uses the or (||) operator and literally means "road_class equals PRIMARY or road_class equals TERTIARY".

There can be multiple such 'if statements' in the speed section, and they are evaluated from top to bottom:

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    },
    {
      "if": "road_class == PRIMARY || road_environment == TUNNEL",
      "multiply_by": "0.7"
    }
  ]
}

In this example the default speed of road segments with road_class == MOTORWAY will be multiplied by 0.5, the default speed of road segments with road_class == PRIMARY will be multiplied by 0.7 and for road segments with both road_class == MOTORWAY and road_environment == TUNNEL the default speed will be multiplied first by 0.5 and then by 0.7. So overall the default speed will be multiplied by 0.35. For road segments with road_class == PRIMARY and road_environment == TUNNEL we only multiply by 0.7, even though both parts of the second condition apply. It only matters whether the road segment matches the condition or not.

road_class and road_environment are road attributes of 'enum' type, i.e. their value can only be one of a fixed set of values, like MOTORWAY for road_class.

Other road attributes like road_class_link are of boolean type. They can be used as conditions directly, for example:

{
  "speed": [
    {
      "if": "road_class_link",
      "multiply_by": "0.6"
    }
  ]
}

which means that for road segments with road_class_link==true the speed factor will be 0.6.

For attributes with numeric values, like max_width you should not use the == (equality) or != ( inequality) operators, but the numerical comparison operators "bigger" >, "bigger or equals" >=, "smaller" <, or "smaller or equals" <=, e.g.:

{
  "speed": [
    {
      "if": "max_width < 2.5",
      "multiply_by": "0.8"
    }
  ]
}

which means that for all road segments with max_width smaller than 2.5m the speed is multiplied by 0.8.

The limit_to operation

Besides the multiply_by operator there is also the limit_to operator. As the name suggests limit_to limits the current value to the given value. Take this example:

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.8"
    },
    {
      "if": "surface == GRAVEL",
      "limit_to": "60"
    }
  ]
}

This implies that on all road segments with the GRAVEL value for surface the speed will be at most 60km/h, regardless of the default speed and the previous rules. So for a road segment with road_class == MOTORWAY, surface == GRAVEL and default speed 100 the first statement reduces the speed from 100 to 80 and the second statement further reduces the speed from 80 to 60. If the road_class was PRIMARY and the default speed was 50 the first rule would not apply and the second rule would do nothing, because limiting 50 to 60 still yields 50.

A common use-case for the limit_to operation is the following pattern:

{
  "speed": [
    {
      "if": "true",
      "limit_to": "90"
    }
  ]
}

which means that the speed is limited to 90km/h for all road segments regardless of its properties. The condition "true" is always fulfilled.

else and else_if statements

The else statement allows you to define that some operations should be applied if an road segment does not match a condition. So this example:

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    },
    {
      "else": "",
      "limit_to": "50"
    }
  ]
}

means that for all road segments with road_class == MOTORWAY we multiply the default speed by 0.5 and for all others we limit the default speed to 50 (but never both).

In case you want to distinguish more than two cases (road segments that match or match not a condition) you can use else_if statements which are only evaluated in case the previous if or else_if statement did not match:

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    },
    {
      "else_if": "road_environment == TUNNEL",
      "limit_to": "70"
    },
    {
      "else": "",
      "multiply_by": "0.9"
    }
  ]
}

So if the first condition matches (road_class == MOTORWAY) the default speed is multiplied by 0.5, but the other two statements are ignored. Only if the first statement does not match (e.g. road_class == PRIMARY) the second statement is even considered and only if it matches (road_environment == TUNNEL) the default speed is limited to 70. The last operation (multiply_by: "0.9") is only applied if both previous conditions did not match.

else and else_if statements always require a preceding if or else_if statement. However, there can be multiple 'blocks' of subsequent if/else_if/else statements in the list of rules for speed.

else_if is useful for example in case you have multiple multiply_by operations, but you do not want that the speed gets reduced by all of them. For the following model

{
  "speed": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    },
    {
      "else_if": "road_environment == TUNNEL",
      "multiply_by": "0.8"
    }
  ]
}

only the first factor (0.5) will be applied even for road segments that fulfill both conditions.

You can not only modify the speed of road segments based on properties, like we saw in the previous examples, but you can also modify the speed of road segments based on their location. To do this you need to first create and add some areas to the areas section of the custom model. You can then use the name of these areas in the conditions of your if/else/else_if statements.

In the following example we multiply the speed of all road segments in an area called custom1 with 0.7 and also limit it to 50km/h. Note that each area's name needs to be prefixed with in_:

{
  "speed": [
    {
      "if": "in_custom1",
      "multiply_by": "0.7"
    },
    {
      "if": "in_custom1",
      "limit_to": "50"
    }
  ],
  "areas": {
    "type": "FeatureCollection",
    "features": [{
      "type": "Feature",
      "id": "custom1",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              1.525,
              42.511
            ],
            [
              1.510,
              42.503
            ],
            [
              1.531,
              42.495
            ],
            [
              1.542,
              42.505
            ],
            [
              1.525,
              42.511
            ]
          ]
        ]
      }
    }]
  }
}

Areas are given in GeoJson format (FeatureCollection). Currently a member of this collection must be a Feature with a geometry type Polygon. Note that the coordinates array of Polygon is an array of arrays that each must describe a closed ring, i.e. the first point must be equal to the last, identical to the GeoJSON specs. Each point is given as an array [longitude, latitude], so the coordinates array has three dimensions total.

Using the areas feature you can also block entire areas i.e. by multiplying the speed with 0, but for this you should rather use the priority section that we will explain next.

Make sure you read the introductory section of this document to learn what the priority factor means. In short it allows similar modifications as speed, but instead of modifying the road segment weights and travel times it will only affect the weights. By default, the priority is 1 for every road segment, so it does not affect the weight. However, changing the priority of a road can yield a relative weight difference in comparison to other roads.

Customizing the priority works very much like changing the speed, so in case you did not read the section about speed you should go back there and read it now. The only real difference is that there is no limit_to operator for priority. As a quick reminder here is an example for priority:

{
  "priority": [
    {
      "if": "road_class == MOTORWAY",
      "multiply_by": "0.5"
    },
    {
      "else_if": "road_class == SECONDARY",
      "multiply_by": "0.9"
    },
    {
      "if": "road_environment == TUNNEL",
      "multiply_by": "0.1"
    }
  ]
}

means that road segments with road_class==MOTORWAY and road_environment==TUNNEL get priority 0.5*0.1=0.05 and those with road_class==SECONDARY and no TUNNEL, get priority 0.9 and so on.

Edges with lower priority values will be less likely part of the optimal route calculated by GraphHopper, higher values mean that these road segments shall be preferred. If you do not want to state which road segments shall be avoided, but rather which ones shall be preferred, you need to decrease the priority of others:

{
  "priority": [
    {
      "if": "road_class != CYCLEWAY",
      "multiply_by": "0.8"
    }
  ]
}

means decreasing the priority for all road_classes except cycleways.

Just like we saw for speed you can also adjust the priority for road segments in a certain area. It works exactly the same way:

{
  "priority": [
    {
      "if": "in_custom1",
      "multiply_by": "0.7"
    }
  ]
}

To block an entire area set the priority value to 0. You can even set the priority only for certain roads in an area like this:

{
  "priority": [
    {
      "if": "road_class == MOTORWAY && in_custom1",
      "multiply_by": "0.1"
    }
  ]
}

Some other useful attributes to restrict access to certain roads depending on your vehicle dimensions are the following:

{
  "priority": [
    {
      "if": "max_width < 2.5",
      "multiply_by": "0"
    },
    {
      "if": "max_length < 10",
      "multiply_by": "0"
    },
    {
      "if": "max_weight < 3.5",
      "multiply_by": "0"
    }
  ]
}

which means that the priority for all road segments that allow a maximum vehicle width of 2.5m, a maximum vehicle length of 10m or a maximum vehicle weight of 3.5tons, or less, is zero, i.e. these "narrow" road segments are blocked.

The distance_influence property allows you to control the trade-off between a fast route (minimum time) and a short route (minimum distance). The larger distance_influence is the more GraphHopper will prioritize routes with a small total distance. More precisely, the distance_influence is the time you need to save on a detour (a longer distance route option) such that you prefer taking the detour compared to a shorter route. Please note that this value is a number, not a string.

A value of 100 means that one extra kilometer of detour must save you 100s of travelling time or else you are not willing to take the detour. Or to put it another way, if a reference route takes 600s and is 10km long, distance_influence=100 means that you are willing to take an alternative route that is 11km long only if it takes no longer than 500s (saves 100s). Things get a bit more complicated when priority is not 1, but the effect stays the same: The larger distance_influence is, the more GraphHopper will focus on finding short routes.

GraphHopper stores different attributes for every road segment. Some frequently used are the following (some of their possible values are given in brackets):

• road_class: (OTHER, MOTORWAY, TRUNK, PRIMARY, SECONDARY, TRACK, STEPS, CYCLEWAY, FOOTWAY, ...)
• road_environment: (ROAD, FERRY, BRIDGE, TUNNEL, ...)
• road_access: (DESTINATION, DELIVERY, PRIVATE, NO, ...)
• surface: (PAVED, DIRT, SAND, GRAVEL, ...)
• smoothness: (EXCELLENT, GOOD, INTERMEDIATE, ...)
• toll: (MISSING, NO, HGV, ALL)
• bike_network, foot_network: (MISSING, INTERNATIONAL, NATIONAL, REGIONAL, LOCAL, OTHER)
• country: (MISSING or the country as a ISO3166-1:alpha3 code e.g. DEU)
• hazmat: (YES, NO), hazmat_tunnel: (A, B, .., E), hazmat_water: (YES, PERMISSIVE, NO)
• hgv: (MISSING, YES, DESIGNATED, ...)
• track_type: (MISSING, GRADE1, GRADE2, ..., GRADE5)
• urban_density: (RURAL, RESIDENTIAL, CITY)

To learn about all available encoded values you can query the /info endpoint

Besides this kind of categories, which can take multiple different string values, there are also some that represent a boolean value (they are either true or false for a given road segment), like:

• road_class_link
• roundabout

There are also some that take on a numeric value, like:

• average_slope: a number for 100 * "elevation change" / edge_distance for a road segment; it changes the sign in reverse direction; see also max_slope
• curvature: "beeline distance" / edge_distance (0..1) e.g. a curvy road is smaller than 1
• hike_rating, horse_rating, mtb_rating: a number from 0 to 6 for the sac_scale in OSM, e.g. 0 means "missing", 1 means "hiking", 2 means "mountain_hiking" and so on
• lanes: number of lanes
• max_slope: an unsigned decimal for the maximum slope (100 * "elevation change / distance_i") of an edge with sum(distance_i)=edge_distance. Important for longer road segments where ups (or downs) can be much bigger than the average_slope.
• max_speed: the speed limit from a sign (km/h)
• max_height (meter), max_width (meter), max_length (meter)
• max_weight (ton), max_axle_load (in tons)

You can directly use custom models with the POST Route Endpoint.

To use custom models with the Route Optimization API or the Matrix API, use the Profiles API to create a new named profile with your custom model. You can then use that profile like you would use a pre-defined profile.

This feature will strongly benefit from feedback, so do not hesitate to share your experience, your favorite custom model or some of the problems you ran into when you tried building your own custom model.

Recommendations

For debugging you can use the custom model editor in GraphHopper Maps (click the 'gear' button in the top left).

When debugging problems with custom models you should first try if your request goes through without an error using an empty custom model.

Route calculation is slower

The route calculation with custom_models will be slower as a different algorithm has to be used. The more the result deviates from the optimum the slower the response can get. Still for certain use cases you can make the calculation faster when you tune the custom_model and e.g. exclude certain ways via { "if": "road_class == TRACK || road_class == RESIDENTIAL", "multiply_by": "0" }.

All routes for my custom model fail

This could mean that either your custom model made some of the roads near the start and destination inaccessible, then usually we return a PointNotFoundException with the point_index with the "location snap" problem.

Or, the custom model made a route between your start and destination impossible, then we return a ConnectionNotFoundException. This happens e.g. when you exclude tunnels, ferries or motorways but all routes between start and destination have these road attributes satisfied, i.e. we cannot find a route.

Solution for both cases: relax your custom model and e.g. instead of excluding certain road attributes via "multiply_by": "0" you should try to use "0.01".

The Route Optimization API can be used to solve traveling salesman or vehicle routing problems. Solve your first problem by following these steps. If you already have a GraphHopper account, start with step 2.

1. Sign up for GraphHopper

2. Create an API key

3. Download simple traveling salesman problem and save it in a local folder

4. Open your command line, go to that local folder and use cURL (What is cURL?) as follows:

   curl -X POST -H "Content-Type: application/json"   "https://graphhopper.com/api/1/vrp?key=YOUR_CREATED_API_KEY" --data "@tsp.json"
   

Alternatively, you can use our API Explorer to explore the Route Optimization API:

1. Select 'Route Optimization API' in the left drop down
2. Paste an existing JSON or select one from the examples
3. Click 'Send' and analyze the solution on the map, in the table or as raw JSON output

If you have successfully solved the first problem, we recommend this tutorial - Getting Started with the Optimization API. It shows and describes the essential elements to model your vehicle routing problem.

To explore the full specification, we recommend that you either use our API explorer which will give you the output as JSON, in a table and directly on a map.

We provide a number of tutorials illustrating how to use the Route Optimization API and how to model your vehicle routing problems:

• Getting Start with the Optimization API - Traveling Salesman Problem
• How to solve a traveling salesman problem with a week-planning horizon?
• How to schedule technicians with skills and multiple dependencies between tasks?
• What is the difference between the min. of completion time and min. transport time?
• How to model multiple delivery routes with a single vehicle?