GraphHopper Directions API

With the GraphHopper Directions API you get reliable and fast web services for routing and more with world wide coverage. We offer A-to-B routing via the Routing API optionally with turn instructions and elevation data as well as route optimization with various constraints like time window and capacity restrictions. Also it is possible to get all distances between all locations with our fast Matrix API.

The GraphHopper Directions API consists of the following parts:

How to Start

  1. To use the Directions API you need an API key. Get it for free here.
  2. Read the documentation below or try the examples in our dashboard.
  3. To increase your query limits for production you pay online within a few minutes via credit card or debit advice.

You can see the Routing and Geocoding API in action at GraphHopper Maps. You can see the Route Optimization API in action in the route editor available in the dashboard, the route optimization uses the Matrix API under the hood.

Problems or Questions?

If you have problems or questions please see the FAQ.md or contact us.

Or search our public forum.

Pricing

The pricing is available here or with all details about monthly/annually in the dashboard.

API Clients and Examples

Let us know your language requirements!

Examples and Applications and Community supported clients:

Do not hesitate to share your websites, apps or API clients with us!

Keep up-to-date

To get informed about the newest features and development follow us at twitter or our blog. Furthermore you can watch this git repository of this documentation, sign up at our dashboard to get the newsletter or sign up at our forum. Pick the channel you like most.

Routing API

Routing Example

The Routing API is documented here.

Route Optimization API

Vehicle Routing Example

The Route Optimization API is documented here.

Isochrone API

Isochrone Example

The Isochrone API is documented here

Map Matching API

Map Matching Example

The Map Matching API is documented here

Matrix API

Matrix Example

The Matrix API is documented here

Geocoding API

Geocoding Example

The Geocoding API is documentation here.

Terms of Services

Read the terms of services carefully and make sure your user are agreeing to be bound by GraphHopper's Terms of Use too.

Attribution

Please read more about how to attribution the usage of the GraphHopper Directions API here.

HTTP Headers

HTTP header key Description
X-RateLimit-Limit Your current daily credit limit
X-RateLimit-Remaining Your remaining credits until the reset
X-RateLimit-Reset The number of seconds that you have to wait before a reset of the credit count is done
X-RateLimit-Credits The credit costs for this request. Note, it could be a decimal and even negative number, e.g. when an async request failed.

HTTP Error codes

HTTP error code Reason
400 Something was wrong in your request. Too few or too many points. ..
401 Authentication necessary
413 Too many parameters in the URL, you'll have to use the JSON format and POST requests
429 API limit reached, you'll also get an email about this, and the header properties will give you more information. See the section about 'HTTP Headers'.
500 Internal server error. We get automatically a notification and will try to fix this fast.
501 Only a special list of vehicles is supported

Error Output

{
  "message": "Cannot find point 2: 2248.224673, 3.867187",
  "hints": [{"message": "something", ...}]
}

Sometimes a point can be "off the road" and you'll get 'cannot find point', this normally does not indicate a bug in the routing engine and is expected to a certain degree if too far away.

JSON path/attribute Description
message Not intended to be displayed to the user as it is currently not translated
hints An optional list of details regarding the error message e.g. [{"message": "first error message in hints"}]