Professional Documents
Culture Documents
Documentation - GraphHopper Directions API
Documentation - GraphHopper Directions API
Documentation - GraphHopper Directions API
com/
With the GraphHopper Directions API you can integrate A-to-B route planning, turn-by-turn navigation,
route optimization, isochrone calculations and other tools in your application.
The GraphHopper Directions API consists of the following RESTful web services:
• Routing API,
• Route Optimization API,
• Isochrone API,
• Map Matching API,
• Matrix API,
• Geocoding API and
• Cluster API.
Get started
Each API part has its own documentation. Jump to the desired API part and learn about the API
through the given examples and tutorials.
In addition, for each API there are specific sample requests that you can send via Insomnia or Postman
to see what the requests and responses look like.
1 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Postman
To speed up development and make coding easier, we offer the following client libraries:
2 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
• Others like C#, Ruby, PHP, Python, ... automatically created for the Route Optimization API
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".
Contact Us
• FAQ
• Public forum
• Contact us
• GraphHopper Status Page
• follow us on twitter,
• read our blog,
• sign up for our newsletter or
• our forum.
Currently, our main data source is OpenStreetMap. We also integrated other network data providers.
This chapter gives an overview about the options you have.
OpenStreetMap
3 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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.
The Routing, Matrix and Route Optimization APIs support the following profiles:
4 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Pedestrian or walking
foot without dangerous foot access foot image
SAC-scales
Pedestrian or walking
with priority for more
beautiful hiking tours
and potentially a bit
hike foot access hike image
longer than foot .
Walking duration is
influenced by
elevation differences.
Trekking bike
bike bike access Bike image
avoiding hills
Mountainbike
mtb Mountainbike bike access
image
Racingbike
racingbike Bike preferring roads bike access
image
Please note:
• the free package supports only the routing profiles car , bike or foot
• up to 2 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, please contact us.
5 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
TomTom
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.
• 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.
Geographical Coverage
We offer
6 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Custom Model
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 == UNCLAS
"multiply_by": "0.1"
}]
}
7 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
{
"distance_influence": 200
}
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.
Customizing speed
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.
{
"speed": [
{
"if": "road_class == MOTORWAY",
"multiply_by": "0.5"
}
]
8 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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 get_off_bike are of boolean type. They can be used as conditions
directly, for example:
9 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
{
"speed": [
{
"if": "get_off_bike",
"multiply_by": "0.6"
}
]
}
which means that for road segments with get_off_bike==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 .
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:
10 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
{
"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 .
{
"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.
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",
11 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
"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
12 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
{
"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": {
"custom1": {
"type": "Feature",
"id": "something",
13 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
"properties": {},
"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, but currently only the exact format in the above example is
supported, i.e. one object with type Feature , a geometry with type Polygon and optional (but
ignored) id and properties fields. 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. 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.
Customizing priority
14 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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"
}
]
}
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"
}
]
}
15 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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:
16 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
{
"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.
Customizing distance_influence
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.
17 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Road attributes
GraphHopper stores different attributes for every road segment. Some frequently used are the following
(some of their possible values are given in brackets):
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:
• get_off_bike
• road_class_link
• roundabout
• 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)
18 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Limitations
1. only available for the POST Route Endpoint. If you are interested in using this for the Matrix or
Route Optimization API please contact us to get access to an early alpha version. For the
Isochrone API it is also planned.
2. only available for the following parent profiles: foot , bike , scooter , car and
small_truck .
3. only available for OpenStreetMap.
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 with
custom model.
Troubleshooting
Recommendations
For debugging you can use the custom model editor in GraphHopper Maps (click the 'custom' button).
When debugging problems with custom models you should first try if your request goes through without
an error using an empty custom model.
For production you should avoid to include road_access and toll in the profile as we will change their
values in the next weeks which could cause unexpected problems.
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 if you tune the custom_model and e.g. exclude certain ways via {
"if": "road_class == TRACK || road_class == RESIDENTIAL", "multiply_by": "0" } .
19 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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 all roads between your start and destination inaccessible, 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: relax your custom model and e.g. instead of excluding certain road attributes via
"multiply_by": "0" you should try to use "0.01" .
Authentication
api_key
Quickstart
20 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
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.
4. Open your command line, go to that local folder and use cURL (What is cURL?) as follows:
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 route editor, which you can find
in our dashboard, or use a REST client such as Insomnia or Postman, as described here.
Tutorials
We provide a number of tutorials illustrating how to use the Route Optimization API and how to model
your vehicle routing problems:
21 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
To solve a new vehicle routing problem, make a HTTP POST to this URL
https://graphhopper.com/api/1/vrp?key=<your_key>
Please note that this URL is very well suited to solve minor problems. Larger vehicle routing problems,
which take longer than 10 seconds to solve, cannot be solved. To solve them, please use the batch
mode URL instead.
AUTHORIZATIONS: api_key
22 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
status string
Enum: "waiting_in_queue" "processing" "finished"
Indicates the current status of the job
23 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
POST /vrp
Request samples
Content type
application/json
24 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
]
- "objectives": [
+ { … },
+ { … }
],
- "configuration": {
+ "routing": { … }
}
}
Response samples
Content type
application/json
25 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
https://graphhopper.com/api/1/vrp/optimize?key=<your_key>
2.) Take the job id and fetch the solution for the vehicle routing problem from this URL:
https://graphhopper.com/api/1/vrp/solution/<job_id>?key=<your_key>
Note: Since the workflow is a bit more cumbersome and since you lose some time in fetching the
solution, you should always prefer the synchronous endpoint. You should use the batch mode only for
long running problems.
AUTHORIZATIONS: api_key
26 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Responses
200 A jobId you can use to retrieve your solution from the server - see solution endpoint.
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
27 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
POST /vrp/optimize
Request samples
Content type
application/json
28 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
],
- "configuration": {
+ "routing": { … }
}
}
Response samples
Content type
application/json
https://graphhopper.com/api/1/vrp/solution/<job_id>?key=<your_key>
You get the job id by sending a vehicle routing problem to the batch mode URL.
AUTHORIZATIONS: api_key
PATH PARAMETERS
jobId string
required
Request solution with jobId
Responses
29 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
status string
Enum: "waiting_in_queue" "processing" "finished"
Indicates the current status of the job
GET /vrp/solution/{jobId}
30 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
GET /vrp/solution/{jobId}
Request samples
Curl Java
Copy
curl -X GET "https://graphhopper.com/api/1/vrp/solution/job_id?key=api_key"
Response samples
Content type
application/json
31 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
The Routing API is part of the GraphHopper Directions API. Routing is the process of finding the best
path connecting two or more points, where the meaning of ''best'' depends on the vehicle profile and
use case.
Tutorials
• You can use the Routing API for navigation: have a look at our open source demo navigation
application and adapt it to your needs. See also this blog post.
• See this blog post on how to retrieve information of the road segments or "per leg".
• Have a look into the custom_model Feature where many requirements can be covered - see
some examples here.
32 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
AUTHORIZATIONS: api_key
QUERY PARAMETERS
33 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
locale string
Default: "en"
The locale of the resulting turn instructions. E.g.
pt_PT for Portuguese or de for German.
elevation boolean
Default: false
If true , a third coordinate, the altitude, is included
with all positions in the response. This changes the
format of the points and snapped_waypoints
fields of the response, in both their encodings. Unless
you switch off the points_encoded parameter, you
need special code on the client side that can handle
three-dimensional coordinates.
optimize string
Default: "false"
Normally, the calculated route will visit the points in
the order you specified them. If you have more than
two points, you can set this parameter to "true"
and the points may be re-ordered to minimize the total
travel time. Keep in mind that the limits on the number
of locations of the Route Optimization API applies,
and the request costs more credits.
34 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
instructions boolean
Default: true
If instructions should be calculated and returned
calc_points boolean
Default: true
If the points for the route should be calculated at all.
debug boolean
Default: false
If true , the output will be formatted.
points_encoded boolean
Default: true
Allows changing the encoding of location data in the
response. The default is polyline encoding, which is
compact but requires special client code to unpack.
(We provide it in our JavaScript client library!) Set this
parameter to false to switch the encoding to
simple coordinate pairs like [lon,lat] , or
[lon,lat,elevation] . See the description of the
response format for more information.
ch.disable boolean
Default: false
Use this parameter in combination with one or more
parameters from below.
pass_through boolean
35 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
pass_through boolean
Default: false
If true , u-turns are avoided at via-points with regard
to the heading_penalty . Requires
ch.disable=true .
algorithm string
Enum: "round_trip" "alternative_route"
Rather than looking for the shortest or fastest path,
this parameter lets you solve two different problems
related to routing: With alternative_route , we
give you not one but several routes that are close to
optimal, but not too similar to each other. With
round_trip , the route will get you back to where
you started. This is meant for fun (think of a bike trip),
so we will add some randomness. The round_trip
option requires ch.disable=true . You can control
both of these features with additional parameters, see
below.
alternative_route.max_weight_factor number
Default: 1.4
If algorithm=alternative_route , this parameter
sets the factor by which the alternatives routes can be
longer than the optimal route. Increasing can lead to
worse alternatives.
alternative_route.max_share_factor number
36 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
alternative_route.max_share_factor number
Default: 0.6
If algorithm=alternative_route , this parameter
specifies how similar an alternative route can be to
the optimal route. Increasing can lead to worse
alternatives.
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
400 Your request is not valid. For example, you specified too few or too many points.
500 Internal server error. We get notified automatically and fix this asap.
37 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
GET /route
Request samples
Curl Java
Copy
curl "https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&profile=ca
Response samples
Content type
application/json
38 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Please see the GET endpoint for alternative method on how to get started. If you are familiar with
POST requests and JSON or you need the custom_model Feature then please continue here.
Especially when you use many locations you should get familiar with this POST endpoint as the GET
endpoint has an URL length limitation. Additionally the request of this POST endpoint can be
compressed and can slightly speed up the request.
To do a request you send JSON data. Both request scenarios GET and POST are identical except that
all singular parameter names are named as their plural for a POST request. The effected parameters
are: points , point_hints and snap_preventions .
Please note that in opposite to the GET endpoint, points are specified in the order of
longitude, latitude .
Note again that also the order changes from latitude,longitude of the GET request to
[longitude,latitude] for the POST request similar to GeoJson.
Example:
AUTHORIZATIONS: api_key
39 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
locale string
Default: "en"
The locale of the resulting turn instructions. E.g.
pt_PT for Portuguese or de for German.
elevation boolean
Default: false
If true , a third coordinate, the altitude, is included
with all positions in the response. This changes the
format of the points and snapped_waypoints
fields of the response, in both their encodings. Unless
you switch off the points_encoded parameter, you
need special code on the client side that can handle
three-dimensional coordinates.
40 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
optimize string
Default: "false"
Normally, the calculated route will visit the points in the
order you specified them. If you have more than two
points, you can set this parameter to "true" and the
points may be re-ordered to minimize the total travel
time. Keep in mind that the limits on the number of
locations of the Route Optimization API applies, and
the request costs more credits.
instructions boolean
Default: true
If instructions should be calculated and returned
calc_points boolean
Default: true
If the points for the route should be calculated at all.
debug boolean
Default: false
If true , the output will be formatted.
points_encoded boolean
Default: true
Allows changing the encoding of location data in the
response. The default is polyline encoding, which is
compact but requires special client code to unpack.
(We provide it in our JavaScript client library!) Set this
parameter to false to switch the encoding to simple
coordinate pairs like [lon,lat] , or
[lon,lat,elevation] . See the description of the
response format for more information.
ch.disable boolean
Default: false
41 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Default: false
Use this parameter in combination with one or more
parameters from below.
{
"points": [
[
13.31543,
52.509535
],
[
13.29779,
52.512434
]
],
"profile": "car",
"ch.disable": true,
"custom_model": {
"speed": [
{
"if": "true",
"limit_to": "100"
}
],
"priority": [
{
"if": "road_class == MOTORWAY",
"multiply_by": "0"
}
],
"distance_influence": 100
}
}
42 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
pass_through boolean
Default: false
If true , u-turns are avoided at via-points with regard
to the heading_penalty . Requires
ch.disable=true .
algorithm string
Enum: "round_trip" "alternative_route"
Rather than looking for the shortest or fastest path, this
parameter lets you solve two different problems related
to routing: With alternative_route , we give you
not one but several routes that are close to optimal, but
not too similar to each other. With round_trip , the
route will get you back to where you started. This is
meant for fun (think of a bike trip), so we will add some
randomness. The round_trip option requires
ch.disable=true . You can control both of these
features with additional parameters, see below.
43 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
alternative_route.max_weight_factor number
Default: 1.4
If algorithm=alternative_route , this parameter
sets the factor by which the alternatives routes can be
longer than the optimal route. Increasing can lead to
worse alternatives.
alternative_route.max_share_factor number
Default: 0.6
If algorithm=alternative_route , this parameter
specifies how similar an alternative route can be to the
optimal route. Increasing can lead to worse
alternatives.
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
44 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
400 Your request is not valid. For example, you specified too few or too many points.
500 Internal server error. We get notified automatically and fix this asap.
POST /route
Request samples
Payload
Content type
application/json
Coverage information
- "details": [
"road_class",
"surface"
Use this to find out details about the supported vehicle profiles and features, or if you just need to ping
the server.
],
"vehicle": "bike",
"locale": "en",
AUTHORIZATIONS: api_key
45 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
AUTHORIZATIONS: api_key
"instructions": true,
"calc_points": true,
"points_encoded": false
Responses
}
Content type
version string
application/json
The version of the GraphHopper server that provided this response. This is
not related to the API version.
Copy Expand all Collapse all
{ bbox string
- "hints": { The bounding box of the geographical area covered by this GraphHopper
instance. Format:
"visited_nodes.sum": 58, `"minLon,minLat,maxLon,maxLat"
"visited_nodes.average": 58
features
}, object
- "info": { The supported features, such as elevation, per vehicle profile.
+ "copyrights": [ … ],
Matrix "took":
API 2
},
- "paths": [
+ { … }
GET
] /route/info
Introduction
}
Response samples
200
Content type
application/json
46 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
"version":
The Matrix "0.4",
API is part of the GraphHopper Directions API and with it you can calculate many-to-many
distances and times a{lot more efficient than calling the Routing API multiple times.
- "features":
+ "foot": { … },
In the Routing API we support multiple points, so called 'via points', which results in one route being
+ "car": { … }
calculated. The Matrix API results in NxM routes, or more precise NxM distances or times being
}
calculated but is a lot faster compared to NxM single requests.
}
The most simple example is a tourist trying to decide which pizza is close to her instead of using
beeline distance she can calculate a 1x4 matrix. Or a delivery service often in the need of big NxN
matrices to solve vehicle routing problems. For example the GraphHopper Route Optimization API
uses the Matrix API under the hood to achieve this.
• Logistic problems often pick up many items from and deliver them to many locations.
• Calculating detours with many possible points in-between and selecting the best e.g. interesting for
ridesharing or taxi applications. For this 1-to-many requests are necessary.
• Finding the best tour for a tourist in the need to visit as many points of interests as possible.
• ...
See the clients section in the main document and live examples.
Description
The Matrix API calculates the well known distance-matrix for a set of points, i.e. it calculates all the
distances between every point combination. But we do not stop there, we also offer a time-, weight-
and route-matrix. The weight-matrix can be used as raw input for e.g. a vehicle routing problem (VRP)
and is more precise than a time- or distance-matrix. E.g. for bike routes the actual weight of a route
(e.g. the "beauty") is what you want to decide if a route is 'better' and not always the taken time or
distance.
A simple illustration for a 3x3 matrix with identical from and to points:
A simple illustration for a 1x3 matrix with different start- and end-points:
47 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
For every route 1->2, 1-3, ... or A->1,A->2,A->3 you can return only the weight, the time and the
distance. To calculate full routes you can use the Routing API.
The cost for one request depends on the number of locations and is documented here.
One request should not exceed the Matrix API location limit, which depends on the subscription, see
the pricing tab in our dashboard.
48 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
AUTHORIZATIONS: api_key
QUERY PARAMETERS
49 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
fail_fast boolean
Default: true
Specifies whether or not the matrix calculation should return with an error as
soon as possible in case some points cannot be found or some points are not
connected. If set to false the time/weight/distance matrix will be calculated
for all valid points and contain the null value for all entries that could not
be calculated. The hint field of the response will also contain additional
information about what went wrong (see its documentation).
Responses
50 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
51 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Array of objects
Optional. Additional response data.
GET /matrix
Request samples
Curl Java
Copy
curl "https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747
Response samples
200 default
Content type
application/json
52 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
- "info": {
+ "copyrights": [ … ]
}
}
Please note that in contrast to GET endpoint the points have to be specified as [longitude,
latitude] array (in that order, similar to GeoJson).
AUTHORIZATIONS: api_key
53 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
fail_fast boolean
Default: true
Specifies whether or not the matrix calculation should return with an error as
soon as possible in case some points cannot be found or some points are not
connected. If set to false the time/weight/distance matrix will be calculated
for all valid points and contain the null value for all entries that could not
be calculated. The hint field of the response will also contain additional
information about what went wrong (see its documentation).
Responses
54 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
55 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
POST /matrix
Request samples
Payload
Content type
application/json
Example
MatrixRequest
56 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
],
"vehicle": "car"
}
Response samples
200 default
Content type
application/json
Batch
}
Matrix Endpoint
Prefer the synchronous endpoint and use this Batch endpoint for long running problems only.
The Batch Matrix endpoint allows using matrices with more locations and works asynchronously -
similar to the Batch Route Optimization endpoint:
• Create a HTTP POST request against /matrix/calculate and add the key in the URL:
/matrix/calculate?key=[YOUR_KEY] . This will give you the job_id from the response json
like { "job_id": "7ac65787-fb99-4e02-a832-2c3010c70097" }
• Poll via HTTP GET requests every 500ms against /matrix/solution/[job_id]
57 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Pick the returned job_id and use it in the next GET requests:
When the calculation is finished ( status:finished ) the JSON response will contain the full matrix
JSON under solution :
Please note that if an error occured while calculation the JSON will not have a status but contain
directly the error message e.g.:
AUTHORIZATIONS: api_key
58 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
to_point
fail_fast boolean
Default: true
Specifies whether or not the matrix calculation should return with an error as
soon as possible in case some points cannot be found or some points are not
connected. If set to false the time/weight/distance matrix will be calculated
for all valid points and contain the null value for all entries that could not
be calculated. The hint field of the response will also contain additional
information about what went wrong (see its documentation).
Responses
200 A jobId you can use to retrieve your solution from the server.
RESPONSE HEADERS
59 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
POST /matrix/calculate
Request samples
Payload
Content type
application/json
Example
MatrixRequest
60 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
+ [ … ]
],
- "to_points": [
+ [ … ],
+ [ … ]
],
- "from_point_hints": [
"Copenhagen Street",
"Richmond Avenue",
"White Lion Street"
],
GET Batch Matrix [Endpoint
- "to_point_hints":
"Cannon",
This endpoint returns the solution of a JSON submitted to the Batch Matrix endpoint. You can fetch it
"Cornhill"
with the],
job_id, you have been sent.
- "out_arrays": [
"weights", api_key
AUTHORIZATIONS:
"times",
PATH PARAMETERS
"distances"
],
jobId
"vehicle": "car"string
required
} Request solution with jobId
Response samples
Responses
200 default
200 A response
Content type containing the matrix
application/json
RESPONSE HEADERS
Copy Expand all Collapse all
{ X-RateLimit-Limit integer
Your current daily credit limit.
"job_id": "44886560-b584-4da5-b245-768151dacd8f"
}
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
61 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
GET /matrix/solution/{jobId}
Response samples
200 default
Content type
application/json
Geocoding
} API
}
62 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Geocoding Endpoint
Introduction
Reverse geocoding converts a coordinate to a textual address representation or place name. Find out
more about Geocoding itself on Wikipedia.
AUTHORIZATIONS: api_key
QUERY PARAMETERS
q string
If you do forward geocoding, this is required and is a textual description of
the address you are looking for.
locale string
Default: "en"
Display the search results for the specified locale. Currently French (fr),
English (en) and German (de) are explicitly supported. Otherwise leave the
locale empty.
reverse boolean
Default: false
It is required to be true if you want to do a reverse geocoding request.
63 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
debug boolean
Default: false
If true , the output will be formatted.
point string
Forward geocoding: The location bias in the format 'latitude,longitude' e.g.
point=45.93272,11.58803. Reverse geocoding: The location to find
amenities, cities.
provider string
Default: "default"
The provider parameter is currently under development and can fall back to
default at any time. The intend is to provide alternatives to our default
geocoder. Each provider has its own strenghts and might fit better for certain
scenarios, so it's worth to compare the different providers. To try it append
the provider parameter to the URL like &provider=nominatim , the
result structure should be identical in all cases - if not, please report this back
to us. Keep in mind that some providers do not support certain parameters or
don't return some fields, for example osm_id and osm_type are not
supported by every geocoding provider. If you would like to use additional
parameters of one of the providers, but it's not available for the GraphHopper
Geocoding API, yet? Please contact us.
The credit costs can be different for all providers - see here for more
information about it.
All providers support normal "forward" geocoding and reverse geocoding via
reverse=true .
Default ( provider=default )
64 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Nominatim ( provider=nominatim )
Gisgraphy ( provider=gisgraphy )
This provider returns results from the Gisgraphy geocoder which you can try
here.
Gisgraphy has a special autocomplete API, which you can use by adding
autocomplete=true (does not work with reverse=true ). The
autocomplete API is optimized on predicting text input, but returns less
information.
NetToolKit ( provider=nettoolkit )
This provider returns results from the NetToolKit provider which is specialized
for US addresses and provides a wrapper around Nominatim for other
addresses. You can try it here.
The following additional NetToolKit parameters are supported (read here for
more details):
65 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
This provider returns results from the OpenCageData geocoder which you
can try here. The difference to the nominatim provider is that other
geocoders might be used under the hood.
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
66 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
GET /geocode
Request samples
Curl Java
Copy
curl "https://graphhopper.com/api/1/geocode?q=berlin&locale=de&key=api_key"
Response samples
200 default
Content type
application/json
67 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Isochrone API
68 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Isochrone Endpoint
Example
curl "https://graphhopper.com/api/1/isochrone?point=51.131108,12.414551&key=[YOUR_KEY]"
Introduction
An isochrone of a location is ''a line connecting points at which a vehicle arrives at the same time'', see
Wikipedia. With the same API you can also calculate isodistances, just use the parameter
distance_limit instead of time_limit`.
Use Cases
69 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
See the clients section in the main documentation, and live examples.
AUTHORIZATIONS: api_key
QUERY PARAMETERS
point string
required
Specify the start coordinate
reverse_flow boolean
Default: false
If false the flow goes from point to the polygon, if true the flow goes
from the polygon "inside" to the point. Example use case for false : How
many potential customer can be reached within 30min travel time from your
store vs. true : How many customers can reach your store within 30min
travel time.
Responses
70 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
L.geoJson(json.polygons).addTo(map)
GET /isochrone
Response samples
200 default
Content type
application/json
71 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
72 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Example
<gpx>
<trk>
<trkseg>
<trkpt lat="51.343657" lon="12.360708"></trkpt>
<trkpt lat="51.343796" lon="12.361337"></trkpt>
<trkpt lat="51.342784" lon="12.361882"></trkpt>
</trkseg>
</trk>
</gpx>
Introduction
The Map Matching API is part of the GraphHopper Directions API and with this API you can snap
73 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
The Map Matching API is part of the GraphHopper Directions API and with this API you can snap
measured GPS points typically as GPX files to a digital road network to e.g. clean data or attach certain
data like elevation or turn instructions to it. Read more at Wikipedia.
In the example screenshot above and demo you see the Map Matching API in action where the black
line is the GPS track and the green one is matched result.
To get a match response you send a GPX file in the body of an HTTP POST request and specify
request parameters like the key and profile in the URL. See below for more supported
parameters.
See the clients section in the main documentation, and live examples.
The cost for one request depends on the number of GPS location and is documented here.
One request should not exceed the Map Matching API location limit depending on the package, see the
pricing in our dashboard.
AUTHORIZATIONS: api_key
QUERY PARAMETERS
gps_accuracy integer
Specify the precision of a point, in meter
locale string
Default: "en"
The locale of the resulting turn instructions. E.g. pt_PT for Portuguese or
de for German.
elevation boolean
Default: false
If true , a third coordinate, the altitude, is included with all positions in the
response. This changes the format of the points and
snapped_waypoints fields of the response, in both their encodings.
Unless you switch off the points_encoded parameter, you need special
74 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
instructions boolean
Default: true
If instructions should be calculated and returned
calc_points boolean
Default: true
If the points for the route should be calculated at all.
points_encoded boolean
Default: true
Allows changing the encoding of location data in the response. The default is
polyline encoding, which is compact but requires special client code to
unpack. (We provide it in our JavaScript client library!) Set this parameter to
false to switch the encoding to simple coordinate pairs like [lon,lat] ,
or [lon,lat,elevation] . See the description of the response format for
more information.
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
75 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
POST /match
Response samples
200 default
Content type
application/json
76 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Cluster API
Introduction
It solves the “capacity clustering problem” by assigning a set of customers to a given number of distinct
groups (called clusters). The API “clusters” by minimizing the total distance from each individual
customer to its designated group median. It can also consider minimum and maximum capacity
restrictions for each group.
77 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Clustering can be used in many practical applications. For example, it can help to plan territories, i.e.
territory optimization for field teams with large territories for field workers, or to solve large vehicle
routing problems (VRP).
The idea is to divide a certain number of customers, a pre-specified number of clusters. As already
written above, a distribution is sought that minimizes the total cost (e.g. distance or time or a function of
distance and time). We currently support two approaches.
1. You can simply define a certain number of clusters via configuration ("clustering" with empty set of
"clusters") and additionally how many customers should be in such a cluster. This is defined by an
upper and lower limit ("min_quantity" and "max_quantity). The algorithm then searches for suitable
clusters and divides the customers into these clusters.
2. You can explicitly define clusters via "clusters". In this way, each individual cluster can be defined.
This approach not only allows each cluster to have its own capacity upper and lower bound, but
each cluster can also be assigned a fixed cluster center. In contrast to 1. the algorithm then does
not search for a suitable center, but assigns the customers given the fixed centers to each cluster.
Note that if you define clusters explicitly, any configuration of "clustering" will be overwritten by
these explicit clusters.
78 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
AUTHORIZATIONS: api_key
Responses
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
79 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
status string
Enum: "waiting_in_queue" "processing" "finished"
Indicates the current status of the job
POST /cluster
Request samples
Payload
Content type
application/json
80 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
AUTHORIZATIONS: api_key
Responses
200 A jobId you can use to retrieve your solution from the server - see solution endpoint.
RESPONSE HEADERS
X-RateLimit-Limit integer
Your current daily credit limit.
X-RateLimit-Remaining integer
Your remaining credits until the reset.
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
credit count is done.
X-RateLimit-Credits integer
The credit costs for this request. Note it could be a decimal and
even negative number, e.g. when an async request failed.
81 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
POST /cluster/calculate
GET Batch Solution Endpoint
Request samples
This endpoint returns the solution of the clustering problems submitted to the Batch Cluster endpoint.
You Payload
can fetch it with the job_id, you have been sent.
Content type
AUTHORIZATIONS: api_key
application/json
PATH PARAMETERS
X-RateLimit-Remaining integer
Response samples
Your remaining credits until the reset.
200 400 500
X-RateLimit-Reset integer
The number of seconds that you have to wait before a reset of the
82 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
Content type The number of seconds that you have to wait before a reset of the
application/json credit count is done.
X-RateLimit-Credits integer
Copy Expand all Collapse all
The credit costs for this request. Note it could be a decimal and
{
even negative number, e.g. when an async request failed.
"job_id": "44886560-b584-4da5-b245-768151dacd8f"
}
RESPONSE SCHEMA: application/json
status string
Enum: "waiting_in_queue" "processing" "finished"
Indicates the current status of the job
GET /cluster/solution/{jobId}
Response samples
Content type
application/json
83 of 84 12/30/2022, 7:23 PM
Documentation - GraphHopper Directions API https://docs.graphhopper.com/
"GraphHopper",
"OpenStreetMap contributors"
],
"status": "finished",
"waiting_time_in_queue": 0,
"processing_time": 4900,
- "clusters": [
+ { … }
]
}
84 of 84 12/30/2022, 7:23 PM