GraphHopper Directions API (1.0.0)

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

The Route Optimization API can be used to solve traveling salesman or vehicle routing problems. You can use our API Explorer to explore Route Optimization. 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.

Further reading:

• 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?

The Routing API calculates the best path connecting two or more points, where the meaning of ''best'' depends on the vehicle profile and use case. Besides path coordinates it can return turn-by-turn instructions, elevation, path details and other useful information about the route.

Use our API Explorer to explore the Routing API.

Geocoding describes the process of transforming an textual address representation to a coordinate (latitude,longitude). For example the conversion from Berlin to 52.5170365,13.3888599.

Reverse geocoding converts a coordinate to a textual address representation or place name. Find out more about Geocoding itself on Wikipedia.

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`.

Some possible areas in which this API may be useful to you:

• real estate analysis
• realtors
• vehicle scheduling
• geomarketing
• reach of electric vehicles
• transport planning
• logistics (distribution and retail network planning)

See the clients section in the main documentation, and our API explorer.

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.

See the clients section in the main documentation, and our API explorer.

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.

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.

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).

Try Clustering in our API Explorer!

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.

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.

You can create routing profiles that are customized to your needs. You can take advantage of all the modelling options described in the Custom Model section and use the created custom profile (prefix cp_) with our Routing, Matrix and Route Optimization APIs.

Important notes

• Each custom profile is limited to a geographic area boundary. Within this boundary there is maximum flexibility for adjusting the profile and you can expect fast response times.
• Currently this feature is only available to selected customers and customers with a premium package. If you are interested please contact us.
• This feature is currently in beta status. It is fully functional, but the API might change in the future. Changes will of course be announced well in advance.
• You can use the following profiles as base profile: car, bike, foot and ecargobike. Contact us if you have different requirements. Motor vehicles can be emulated like done for truck in this post.

A curl example:

curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/profiles?key=YOUR_KEY" -d '{"bounds":{"bbox":[11.45462,48.00954,11.77322,48.2076]},"custom_model":{"priority":[{"if":"road_class == MOTORWAY","multiply_by":"0"}]},"profile":"car"}'

If you plan to tweak your custom_model frequently it is recommended to initially use the Routing API where a different custom model can be specified in every request. Or use GraphHopper Maps and click the gear button.

Creating custom profiles using the API Explorer

Besides using the /profiles endpoint directly you can also create custom profiles from our API explorer.

1. Visit the API explorer.
2. Set your API key with the "API key" button. If an error occurs we might have to activate custom profiles for your account before you can continue. Contact us.
3. Now copy and paste the JSON to create a custom profile into the input window. To get started you can use the already pre-filled example, which will create a custom profile that excludes motorways and is limited to the Munich area.
4. Click "Send". This creates a custom profile. Copy the returned id from the output window (it starts with cp_).
5. To try this profile out you now change the drop down to "Optimization API", pick the first example and replace "car" in "profile": "car" (vehicle_types section) with the profile id and click "Send":

You should now see that the solution no longer uses motorways. Keep in mind that this is a simple example. The custom model language is a lot more powerful than this. Make sure you read the Custom Model section to learn about all the details.

Note that you can use the profile id just as well for the /matrix or /route endpoint. E.g. select "Routing API" and use the profile id in the request: