GraphHopper Directions API

Batch Cluster Endpoint Prefer the [synchronous endpoint](#operation/solveClusteringProblem) 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=` 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/?key=`.

POST route optimization problem (batch mode) 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= ``` 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/?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](#operation/solveVRP). You should use the batch mode only for long running problems.

Batch Matrix Endpoint Prefer the [synchronous endpoint](#operation/postMatrix) 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](#operation/asyncVRP): * 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.

GET Batch Solution Endpoint This endpoint returns the solution of the clustering problems submitted to the [Batch Cluster endpoint](#operation/asyncClusteringProblem). You can fetch it with the job_id, you have been sent.

Geocoding Endpoint ### 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](http://en.wikipedia.org/wiki/Geocoding).

Isochrone Endpoint ### 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/API-Clients) section in the main documentation, and [live examples](https://graphhopper.com/api/1/examples/#isochrone).

GET Matrix Endpoint 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](#operation/postMatrix) that avoids problems with many locations and can also gzip the **request**. (Note, that all endpoints return gzipped responses).

GET Batch Matrix Endpoint 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.

GET Route Endpoint 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.

GET the solution (batch mode) Take the job id and fetch the solution for the vehicle routing problem from this URL: ``` https://graphhopper.com/api/1/vrp/solution/?key= ``` You get the job id by sending a vehicle routing problem to the [batch mode URL](#operation/asyncVRP).

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

Map-match a GPX file ### 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 ``` ### 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](#tag/Routing-API) apply here, too. ### API Clients and Examples See the [clients](#section/API-Clients) section in the main documentation, and [live examples](https://graphhopper.com/api/1/examples/#map-matching). ### Limits and Counts The cost for one request depends on the number of GPS location and is documented [here](https://graphhopper.com/api/1/docs/FAQ/). One request should not exceed the Map Matching API location limit depending on the package, see the pricing in our dashboard.

POST Matrix Endpoint The [GET endpoint](#operation/getMatrix) 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](#operation/getMatrix). **Please note that in contrast to GET endpoint the points have to be specified as `[longitude, latitude]` array (in that order, similar to [GeoJson](http://geojson.org/geojson-spec.html#examples))**. 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"}' ```

POST Route Endpoint Please see the [GET endpoint](#operation/getRoute) 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](http://geojson.org/geojson-spec.html#examples). 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"}' ```

POST Cluster Endpoint The Cluster endpoint is used with a POST request towards `https://graphhopper.com/api/1/cluster?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](#operation/asyncClusteringProblem) instead.

POST route optimization problem To get started with the Route Optimization API, please read the [introduction](#tag/Route-Optimization-API). To solve a new vehicle routing problem, make a HTTP POST to this URL ``` https://graphhopper.com/api/1/vrp?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](#operation/asyncVRP) instead.