Tools (18)

Extracted live via the executor SDK.

• clusterApi.asyncClusteringProblem

  Prefer the synchronous endpoint and use this Batch Cluster endpoint for long running problems only. The work flow is asynchronous:

  • send a POST request towards https://graphhopper.com/api/1/cluster/calculate?key=<your_key> and fetch the job_id.
  • poll the solution every 500ms until it gives status=finished. Do this with a GET request towards https://graphhopper.com/api/1/cluster/solution/<job_id>?key=<your_key>.
• clusterApi.getClusterSolution

  This endpoint returns the solution of the clustering problems submitted to the Batch Cluster endpoint. You can fetch it with the job_id, you have been sent.

• clusterApi.solveClusteringProblem

  The Cluster endpoint is used with a POST request towards https://graphhopper.com/api/1/cluster?key=<your_key>. The solution will be provided in the JSON response. Please note that for problems that take longer than 10 seconds a bad request error is returned. In this case please use the asynchronous Batch Cluster Endpoint instead.

• geocodingApi.getGeocode

  Introduction

  

  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.

• isochroneApi.getIsochrone

  Example

  You can get an example response via:

  curl "https://graphhopper.com/api/1/isochrone?point=51.131108,12.414551&key=[YOUR_KEY]"

  Don't forget to replace the placeholder with your own 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

  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)

  API Clients and Examples

  See the clients section in the main documentation, and live examples. `

• mapMatchingApi.postGpx

  Example

  You get an example response for a GPX via:

  curl -XPOST -H "Content-Type: application/gpx+xml" "https://graphhopper.com/api/1/match?vehicle=car&key=[YOUR_KEY]" --data @/path/to/some.gpx

  A minimal working GPX file looks like

  gpx

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

  Most of the times, you can simply POST a GPX file, but some of the request parameters of the Routing API apply here, too.

  API Clients and Examples

  See the clients section in the main documentation, and live examples.

  Limits and Counts

  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.

• matrixApi.calculateMatrix

  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]

  Here are some full examples via curl:

  bash

  $ curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix/calculate?key=[YOUR_KEY]" -d '{"points":[[13.29895,52.48696],[13.370876,52.489575],[13.439026,52.511206]]}'{"job_id":"7ac65787-fb99-4e02-a832-2c3010c70097"}

  Pick the returned job_id and use it in the next GET requests:

  bash

  $ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"{"status":"waiting"}

  When the calculation is finished (status:finished) the JSON response will contain the full matrix JSON under solution:

  bash

  $ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"{"solution":{"weights":[[0.0,470.453,945.414],[503.793,0.0,580.871],[970.49,569.511,0.0]],"info":{"copyrights":["GraphHopper","OpenStreetMap contributors"]}},"status":"finished"}

  Please note that if an error occured while calculation the JSON will not have a status but contain directly the error message e.g.:

  json

  {"message":"Cannot find from_points: 1"}

  And the optional hints array.

• matrixApi.getMatrix

  With this Matrix Endpoint you submit the points and parameters via URL parameters and is the most convenient as it works out-of-the-box in the browser. If possible you should prefer using the POST Matrix Endpoint that avoids problems with many locations and can also gzip the request. (Note, that all endpoints return gzipped responses).

• matrixApi.getMatrixSolution

  This endpoint returns the solution of a JSON submitted to the Batch Matrix endpoint. You can fetch it with the job_id, you have been sent.

• matrixApi.postMatrix

  The GET endpoint has an URL length limitation, which hurts for many locations per request. In those cases use this POST endpoint with a JSON as input. The only parameter in the URL will be the key. Both request scenarios are identical except that all singular parameter names are named as their plural for a POST request. The effected parameters are: points, from_points, to_points, and out_arrays. For the remaining parameters please refer to the guide of the GET endpoint.

  Please note that in contrast to GET endpoint the points have to be specified as [longitude, latitude] array (in that order, similar to GeoJson).

  For example the query point=10,11&point=20,22&vehicle=car will be converted to the following JSON:

  json

  { "points": [[11,10], [22,20]], "vehicle": "car" }

  A complete curl Example:

  bash

  curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix?key=[YOUR_KEY]" -d '{"elevation":false,"out_arrays":["weights", "times"],"from_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"to_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"vehicle":"car"}'

• routeOptimizationApi.asyncVrp

  To solve a vehicle routing problem, perform the following steps:

  1.) Make a HTTP POST to this URL

  https://graphhopper.com/api/1/vrp/optimize?key=<your_key>

  It returns a job id (job_id).

  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>

  We recommend to query the solution every 500ms until it returns 'status=finished'.

  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.

• routeOptimizationApi.getSolution

  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>

  You get the job id by sending a vehicle routing problem to the batch mode URL.

• routeOptimizationApi.solveVrp

  To get started with the Route Optimization API, please read the introduction.

  To solve a new vehicle routing problem, make a HTTP POST to this URL

  https://graphhopper.com/api/1/vrp?key=<your_key>

  It returns the solution to this problem in the JSON response.

  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.

• routingApi.getRoute

  The GET request is the most simple one: just specify the parameter in the URL and you are done. Can be tried directly in every browser.

• routingApi.getRouteInfo

  Use this to find out details about the supported vehicle profiles and features, or if you just need to ping the server.

• routingApi.postRoute

  Please see the GET endpoint for a simpler method on how to get started. If you are familiar with POST requests and JSON then do not hesitate to 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.

  For example point=10,11&point=20,22 will be converted to the points array (plural):

  json

  { "points": [[11,10], [22,20]] }

  Note again that also the order changes from [latitude,longitude] to [longitude,latitude] similar to GeoJson.

  Example:

  bash

  curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/route?key=[YOUR_KEY]" -d '{"elevation":false,"points":[[-0.087891,51.534377],[-0.090637,51.467697]],"vehicle":"car"}'

• openapi.previewSpec

  Preview an OpenAPI document before adding it as a source

• openapi.addSource

  Add an OpenAPI source and register its operations as tools