Download OpenAPI specification:Download
With the GraphHopper Directions API you can integrate A-to-B route planning, turn-by-turn navigation, route optimization, isochrone calculations, location clustering and other tools in your application.
The GraphHopper Directions API consists of the following RESTful web services:
Each API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials.
You can also try all API parts without registration in our API explorer.
To speed up development and make coding easier, we offer a JavaScript client and a Java client.
Reuse SSL/TLS sessions
You should utilize the SSL session to speed up responses after the initial response or use a library that does this. E.g. for Java the
OkHttp library automatically reuses SSL/TLS sessions and also the browser takes care of this automatically.
For python you can use the requests
library: first you create a
session (session = requests.Session()
) and then do requests only with this session instead of directly using "requests".
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 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".
If you have problems or questions, please read the following information:
To stay informed about the latest developments, you can
The default data source is OpenStreetMap and as an alternative we have also integrated TomTom.
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. But also see the section about customized profiles below the table.
Name | Description | Restrictions | Icon |
---|---|---|---|
car | Car mode | car access, weight=2500kg, width=2m, height=2m | |
car_avoid_motorway | Car mode | like car that heavily penalizes motorways | |
car_avoid_ferry | Car mode | like car that heavily penalizes ferries | |
car_avoid_toll | Car mode | like car that heavily penalizes tolls and ferries | |
small_truck | Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.28m, length=5.5m, weight=2080+1400 kg | |
truck | Truck like a MAN or Mercedes-Benz Actros | height=3.7m, width=2.6+0.34m, length=12m, weight=13000+13000 kg, hgv=yes, 3 Axes | |
scooter | Moped mode | Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h. weight=300kg, width=1m, height=2m | |
foot | Pedestrian or walking without dangerous SAC-scales | foot access | |
hike | Pedestrian or walking with priority for more beautiful hiking tours and potentially a bit longer than foot . Walking duration is influenced by elevation differences. |
foot access | |
bike | Trekking bike avoiding hills | bike access | |
mtb | Mountainbike | bike access | |
racingbike | Bike preferring roads | bike access | |
ecargobike | Similar to racingbike but a bit faster and with width constraints. Currently only available upon request. | bike access but without steps and footways | |
as_the_crow_flies | Only available for the Cluster API. Uses the straight-line (or "direct") distance. This allows to use 5x more customers than the contractual "locations" limit defines. | - | - |
Please note:
car
, bike
or foot
motorcycle
profile is available up on request. It is powered by the Kurviger Routing API and favors curves and slopes while avoiding cities and highways.You can also adjust the speeds, access options and much more by using customized routing profiles. We offer this for the Routing API (see the section about Custom Models). For interested customers we offer the Profiles API that can be used for matrix calculations and route optimiztion as well.
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.
Please note the following:
Contact us if you want to buy this TomTom add-on.
We offer
Name | Description | Restrictions | Icon |
---|---|---|---|
car | Car mode | car access | |
small_truck | Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.28m, length=5.5m, weight=2080+1400 kg |
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.
Download simple traveling salesman problem and save it in a local folder
Open your command line, go to that local folder and use cURL (What is cURL?) as follows:
curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/vrp?key=YOUR_CREATED_API_KEY" --data "@tsp.json"
Alternatively, you can use our API Explorer to explore the Route Optimization API:
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 API explorer which will give you the output as JSON, in a table and directly on a map.
We provide a number of tutorials illustrating how to use the Route Optimization API and how to model your vehicle routing problems:
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.
The request that contains the vehicle routing problem to be solved.
Array of objects (Vehicle) non-empty Specifies the available vehicles. | |
Array of objects (VehicleType) Specifies the available vehicle types. These types can be assigned to vehicles. | |
Array of objects (Service) Specifies the orders of the type "service". These are, for example, pick-ups, deliveries or other stops that are to be approached by the specified vehicles. Each of these orders contains only one location. | |
Array of objects (Shipment) Specifies the available shipments. Each shipment consists of a pickup and a delivery. For a single shipment, the pickup must always occur before the delivery. However, pickups and deliveries from multiple shipments can be sequenced independently. | |
Array of JobRelation (object) or GroupRelation (object) Defines additional relationships between orders. | |
object (Algorithm) Deprecated Use | |
Array of objects (Objective) Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized. | |
Array of objects (CostMatrix) Specifies your own tranport time and distance matrices. | |
object (Configuration) Specifies general configurations. |
A response containing the solution
Error occurred when reading the request. Request is invalid.
Error occurred on server side.
{- "vehicles": [
- {
- "vehicle_id": "vehicle-1",
- "type_id": "cargo-bike",
- "start_address": {
- "location_id": "berlin",
- "lon": 13.406,
- "lat": 52.537
}, - "earliest_start": 1554804329,
- "latest_end": 1554808329,
- "max_jobs": 3
}, - {
- "vehicle_id": "vehicle-2",
- "type_id": "cargo-bike",
- "start_address": {
- "location_id": "berlin",
- "lon": 13.406,
- "lat": 52.537
}, - "earliest_start": 1554804329,
- "latest_end": 1554808329,
- "max_jobs": 3,
- "skills": [
- "physical strength"
]
}
], - "vehicle_types": [
- {
- "type_id": "cargo-bike",
- "capacity": [
- 10
], - "profile": "bike"
}
], - "services": [
- {
- "id": "s-1",
- "name": "visit-Joe",
- "address": {
- "location_id": "13.375854_52.537338",
- "lon": 13.375854,
- "lat": 52.537338
}, - "size": [
- 1
], - "time_windows": [
- {
- "earliest": 1554805329,
- "latest": 1554806329
}
]
}, - {
- "id": "s-2",
- "name": "serve-Peter",
- "address": {
- "location_id": "13.393364_52.525851",
- "lon": 13.393364,
- "lat": 52.525851
}, - "size": [
- 1
]
}, - {
- "id": "s-3",
- "name": "visit-Michael",
- "address": {
- "location_id": "13.416882_52.523543",
- "lon": 13.416882,
- "lat": 52.523543
}, - "size": [
- 1
]
}, - {
- "id": "s-4",
- "name": "do nothing",
- "address": {
- "location_id": "13.395767_52.514038",
- "lon": 13.395767,
- "lat": 52.514038
}, - "size": [
- 1
]
}
], - "shipments": [
- {
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "name": "pickup and deliver pizza to Peter",
- "priority": 1,
- "pickup": {
- "address": {
- "location_id": "13.387613_52.529961",
- "lon": 13.387613,
- "lat": 52.529961
}
}, - "delivery": {
- "address": {
- "location_id": "13.380575_52.513614",
- "lon": 13.380575,
- "lat": 52.513614
}
}, - "size": [
- 1
], - "required_skills": [
- "physical strength"
]
}
], - "objectives": [
- {
- "type": "min",
- "value": "vehicles"
}, - {
- "type": "min",
- "value": "completion_time"
}
], - "configuration": {
- "routing": {
- "calc_points": true,
- "snap_preventions": [
- "motorway",
- "trunk",
- "tunnel",
- "bridge",
- "ferry"
]
}
}
}
{- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "job_id": "d62fcadd-c84a-4298-90b5-28550125bec5",
- "status": "finished",
- "waiting_time_in_queue": 0,
- "processing_time": 459,
- "solution": {
- "costs": 438,
- "distance": 17994,
- "time": 4094,
- "transport_time": 4094,
- "completion_time": 4172,
- "max_operation_time": 2465,
- "waiting_time": 78,
- "service_duration": 0,
- "preparation_time": 0,
- "no_vehicles": 2,
- "no_unassigned": 0,
- "routes": [
- {
- "vehicle_id": "vehicle-2",
- "distance": 10618,
- "transport_time": 2465,
- "completion_time": 2465,
- "waiting_time": 0,
- "service_duration": 0,
- "preparation_time": 0,
- "points": [
- {
- "coordinates": [
- [
- 13.40608,
- 52.53701
], - [
- 13.40643,
- 52.53631
], - [
- 13.40554,
- 52.53616
], - [
- 13.4054,
- 52.53608
], - [
- 13.40445,
- 52.53513
], - [
- 13.40436,
- 52.53509
], - [
- 13.40428,
- 52.53508
], - [
- 13.40463,
- 52.53419
], - [
- 13.40451,
- 52.53419
], - [
- 13.4034,
- 52.53401
], - [
- 13.403,
- 52.53359
], - [
- 13.40291,
- 52.53354
], - [
- 13.40268,
- 52.53347
], - [
- 13.39888,
- 52.53259
], - [
- 13.39839,
- 52.53253
], - [
- 13.39812,
- 52.53251
], - [
- 13.39616,
- 52.53243
], - [
- 13.39579,
- 52.5324
], - [
- 13.38973,
- 52.53173
], - [
- 13.39163,
- 52.53025
], - [
- 13.38797,
- 52.52935
], - [
- 13.38763,
- 52.52996
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.38763,
- 52.52996
], - [
- 13.38739,
- 52.53039
], - [
- 13.38724,
- 52.53036
], - [
- 13.38464,
- 52.52929
], - [
- 13.38538,
- 52.52871
], - [
- 13.38634,
- 52.52792
], - [
- 13.38638,
- 52.52779
], - [
- 13.38657,
- 52.52763
], - [
- 13.38676,
- 52.52741
], - [
- 13.38698,
- 52.52713
], - [
- 13.38704,
- 52.52701
], - [
- 13.38753,
- 52.524
], - [
- 13.3877,
- 52.52307
], - [
- 13.3878,
- 52.52282
], - [
- 13.38788,
- 52.52252
], - [
- 13.38802,
- 52.52174
], - [
- 13.38519,
- 52.52009
], - [
- 13.38539,
- 52.5191
], - [
- 13.38548,
- 52.51852
], - [
- 13.38042,
- 52.51819
], - [
- 13.38071,
- 52.5167
], - [
- 13.38076,
- 52.51652
], - [
- 13.38084,
- 52.51634
], - [
- 13.3821,
- 52.51396
], - [
- 13.38055,
- 52.51365
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.38055,
- 52.51365
], - [
- 13.38229,
- 52.514
], - [
- 13.38363,
- 52.51429
], - [
- 13.3848,
- 52.51445
], - [
- 13.38504,
- 52.51358
], - [
- 13.39124,
- 52.51397
], - [
- 13.3911,
- 52.51488
], - [
- 13.39303,
- 52.51499
], - [
- 13.39317,
- 52.5141
], - [
- 13.39548,
- 52.51419
], - [
- 13.39571,
- 52.51421
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.39571,
- 52.51421
], - [
- 13.39695,
- 52.51434
], - [
- 13.39674,
- 52.51523
], - [
- 13.39742,
- 52.51531
], - [
- 13.39873,
- 52.51558
], - [
- 13.39846,
- 52.51599
], - [
- 13.39825,
- 52.51729
], - [
- 13.39805,
- 52.51755
], - [
- 13.39892,
- 52.51761
], - [
- 13.39917,
- 52.51764
], - [
- 13.39964,
- 52.51775
], - [
- 13.40009,
- 52.51791
], - [
- 13.40034,
- 52.51797
], - [
- 13.4021,
- 52.51864
], - [
- 13.40288,
- 52.51896
], - [
- 13.40375,
- 52.51936
], - [
- 13.40498,
- 52.52001
], - [
- 13.40463,
- 52.5203
], - [
- 13.40311,
- 52.52144
], - [
- 13.40442,
- 52.52189
], - [
- 13.40448,
- 52.52192
], - [
- 13.40451,
- 52.52195
], - [
- 13.40473,
- 52.52199
], - [
- 13.40504,
- 52.52208
], - [
- 13.40572,
- 52.52235
], - [
- 13.40687,
- 52.52294
], - [
- 13.40693,
- 52.52299
], - [
- 13.40706,
- 52.52319
], - [
- 13.40738,
- 52.52378
], - [
- 13.40787,
- 52.52443
], - [
- 13.4079,
- 52.52453
], - [
- 13.40938,
- 52.52401
], - [
- 13.40962,
- 52.52398
], - [
- 13.41001,
- 52.52395
], - [
- 13.41072,
- 52.52391
], - [
- 13.41215,
- 52.52389
], - [
- 13.41233,
- 52.52386
], - [
- 13.4131,
- 52.5235
], - [
- 13.41288,
- 52.52333
], - [
- 13.41475,
- 52.52247
], - [
- 13.41496,
- 52.52264
], - [
- 13.41523,
- 52.52251
], - [
- 13.41633,
- 52.52338
], - [
- 13.41631,
- 52.52346
], - [
- 13.41654,
- 52.52364
], - [
- 13.41684,
- 52.52351
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.41684,
- 52.52351
], - [
- 13.41654,
- 52.52364
], - [
- 13.41631,
- 52.52346
], - [
- 13.4163,
- 52.52344
], - [
- 13.41587,
- 52.52363
], - [
- 13.41572,
- 52.5235
], - [
- 13.41409,
- 52.5242
], - [
- 13.41454,
- 52.52461
], - [
- 13.41454,
- 52.52466
], - [
- 13.41358,
- 52.52508
], - [
- 13.41366,
- 52.52514
], - [
- 13.41344,
- 52.52525
], - [
- 13.4133,
- 52.52514
], - [
- 13.41316,
- 52.5252
], - [
- 13.41107,
- 52.52585
], - [
- 13.41118,
- 52.52606
], - [
- 13.41118,
- 52.52616
], - [
- 13.41095,
- 52.52664
], - [
- 13.41097,
- 52.52678
], - [
- 13.41084,
- 52.52706
], - [
- 13.41057,
- 52.52747
], - [
- 13.41028,
- 52.52809
], - [
- 13.41032,
- 52.52821
], - [
- 13.4102,
- 52.52847
], - [
- 13.40999,
- 52.52875
], - [
- 13.40984,
- 52.52905
], - [
- 13.40982,
- 52.52914
], - [
- 13.40984,
- 52.52926
], - [
- 13.4104,
- 52.52998
], - [
- 13.4105,
- 52.53001
], - [
- 13.41064,
- 52.53016
], - [
- 13.41082,
- 52.5303
], - [
- 13.41198,
- 52.53107
], - [
- 13.4122,
- 52.53128
], - [
- 13.41232,
- 52.53143
], - [
- 13.41247,
- 52.53192
], - [
- 13.41267,
- 52.53245
], - [
- 13.41275,
- 52.53259
], - [
- 13.41215,
- 52.5327
], - [
- 13.40731,
- 52.53463
], - [
- 13.40608,
- 52.53701
]
], - "type": "LineString"
}
], - "activities": [
- {
- "type": "start",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "end_time": 1554804329,
- "end_date_time": null,
- "distance": 0,
- "driving_time": 0,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_after": [
- 0
]
}, - {
- "type": "pickupShipment",
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "location_id": "13.387613_52.529961",
- "address": {
- "location_id": "13.387613_52.529961",
- "lat": 52.529961,
- "lon": 13.387613
}, - "arr_time": 1554804789,
- "arr_date_time": null,
- "end_time": 1554804789,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 2012,
- "driving_time": 460,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "deliverShipment",
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "location_id": "13.380575_52.513614",
- "address": {
- "location_id": "13.380575_52.513614",
- "lat": 52.513614,
- "lon": 13.380575
}, - "arr_time": 1554805344,
- "arr_date_time": null,
- "end_time": 1554805344,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 4560,
- "driving_time": 1015,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 0
]
}, - {
- "type": "service",
- "id": "s-4",
- "location_id": "13.395767_52.514038",
- "address": {
- "location_id": "13.395767_52.514038",
- "lat": 52.514038,
- "lon": 13.395767
}, - "arr_time": 1554805632,
- "arr_date_time": null,
- "end_time": 1554805632,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 5887,
- "driving_time": 1303,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "service",
- "id": "s-3",
- "location_id": "13.416882_52.523543",
- "address": {
- "location_id": "13.416882_52.523543",
- "lat": 52.523543,
- "lon": 13.416882
}, - "arr_time": 1554806253,
- "arr_date_time": null,
- "end_time": 1554806253,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 8486,
- "driving_time": 1924,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 2
]
}, - {
- "type": "end",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "arr_time": 1554806794,
- "arr_date_time": null,
- "distance": 10618,
- "driving_time": 2465,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_before": [
- 2
]
}
]
}, - {
- "vehicle_id": "vehicle-1",
- "distance": 7376,
- "transport_time": 1629,
- "completion_time": 1707,
- "waiting_time": 78,
- "service_duration": 0,
- "preparation_time": 0,
- "points": [
- {
- "coordinates": [
- [
- 13.40608,
- 52.53701
], - [
- 13.40674,
- 52.53571
], - [
- 13.40433,
- 52.53313
], - [
- 13.40271,
- 52.53149
], - [
- 13.40246,
- 52.53121
], - [
- 13.40148,
- 52.52999
], - [
- 13.40128,
- 52.52993
], - [
- 13.40118,
- 52.52988
], - [
- 13.40133,
- 52.5296
], - [
- 13.40138,
- 52.52951
], - [
- 13.40167,
- 52.52914
], - [
- 13.40188,
- 52.52895
], - [
- 13.398,
- 52.52885
], - [
- 13.39289,
- 52.52748
], - [
- 13.39354,
- 52.5264
], - [
- 13.39358,
- 52.52628
], - [
- 13.39324,
- 52.52575
], - [
- 13.39334,
- 52.52573
], - [
- 13.39339,
- 52.52584
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.39339,
- 52.52584
], - [
- 13.3934,
- 52.52599
], - [
- 13.39358,
- 52.52628
], - [
- 13.39354,
- 52.5264
], - [
- 13.39242,
- 52.52823
], - [
- 13.39381,
- 52.52852
], - [
- 13.38973,
- 52.53173
], - [
- 13.38717,
- 52.5315
], - [
- 13.38678,
- 52.5315
], - [
- 13.38641,
- 52.53147
], - [
- 13.38617,
- 52.53143
], - [
- 13.38607,
- 52.53155
], - [
- 13.38526,
- 52.53225
], - [
- 13.38501,
- 52.53252
], - [
- 13.38316,
- 52.53418
], - [
- 13.38179,
- 52.5355
], - [
- 13.38084,
- 52.53523
], - [
- 13.38081,
- 52.53531
], - [
- 13.3795,
- 52.53677
], - [
- 13.37941,
- 52.53682
], - [
- 13.37935,
- 52.53683
], - [
- 13.37919,
- 52.53682
], - [
- 13.37617,
- 52.5361
], - [
- 13.37502,
- 52.53698
], - [
- 13.37584,
- 52.53734
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.37584,
- 52.53734
], - [
- 13.37566,
- 52.53726
], - [
- 13.37515,
- 52.53763
], - [
- 13.37644,
- 52.53841
], - [
- 13.37807,
- 52.53935
], - [
- 13.37946,
- 52.5402
], - [
- 13.3796,
- 52.54019
], - [
- 13.37984,
- 52.54021
], - [
- 13.37988,
- 52.54012
], - [
- 13.38062,
- 52.53936
], - [
- 13.38169,
- 52.53832
], - [
- 13.38236,
- 52.5377
], - [
- 13.38363,
- 52.53661
], - [
- 13.38492,
- 52.53555
], - [
- 13.38613,
- 52.53447
], - [
- 13.38757,
- 52.53338
], - [
- 13.38791,
- 52.53354
], - [
- 13.38812,
- 52.53368
], - [
- 13.38833,
- 52.53392
], - [
- 13.38977,
- 52.53518
], - [
- 13.39003,
- 52.53539
], - [
- 13.39256,
- 52.53701
], - [
- 13.39316,
- 52.53739
], - [
- 13.39327,
- 52.53744
], - [
- 13.3936,
- 52.53757
], - [
- 13.40155,
- 52.53982
], - [
- 13.40357,
- 52.53715
], - [
- 13.40372,
- 52.53719
], - [
- 13.40465,
- 52.53727
], - [
- 13.4048,
- 52.53726
], - [
- 13.4059,
- 52.53736
], - [
- 13.40608,
- 52.53701
]
], - "type": "LineString"
}
], - "activities": [
- {
- "type": "start",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "end_time": 1554804329,
- "end_date_time": null,
- "distance": 0,
- "driving_time": 0,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_after": [
- 0
]
}, - {
- "type": "service",
- "id": "s-2",
- "location_id": "13.393364_52.525851",
- "address": {
- "location_id": "13.393364_52.525851",
- "lat": 52.525851,
- "lon": 13.393364
}, - "arr_time": 1554804743,
- "arr_date_time": null,
- "end_time": 1554804743,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 1884,
- "driving_time": 414,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "service",
- "id": "s-1",
- "location_id": "13.375854_52.537338",
- "address": {
- "location_id": "13.375854_52.537338",
- "lat": 52.537338,
- "lon": 13.375854
}, - "arr_time": 1554805251,
- "arr_date_time": null,
- "end_time": 1554805329,
- "end_date_time": null,
- "waiting_time": 78,
- "distance": 4205,
- "driving_time": 922,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 2
]
}, - {
- "type": "end",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "arr_time": 1554806036,
- "arr_date_time": null,
- "distance": 7376,
- "driving_time": 1629,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_before": [
- 2
]
}
]
}
], - "unassigned": {
- "services": [ ],
- "shipments": [ ],
- "breaks": [ ],
- "details": [ ]
}
}
}
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.
The request that contains the problem to be solved.
Array of objects (Vehicle) non-empty Specifies the available vehicles. | |
Array of objects (VehicleType) Specifies the available vehicle types. These types can be assigned to vehicles. | |
Array of objects (Service) Specifies the orders of the type "service". These are, for example, pick-ups, deliveries or other stops that are to be approached by the specified vehicles. Each of these orders contains only one location. | |
Array of objects (Shipment) Specifies the available shipments. Each shipment consists of a pickup and a delivery. For a single shipment, the pickup must always occur before the delivery. However, pickups and deliveries from multiple shipments can be sequenced independently. | |
Array of JobRelation (object) or GroupRelation (object) Defines additional relationships between orders. | |
object (Algorithm) Deprecated Use | |
Array of objects (Objective) Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized. | |
Array of objects (CostMatrix) Specifies your own tranport time and distance matrices. | |
object (Configuration) Specifies general configurations. |
A jobId you can use to retrieve your solution from the server - see solution endpoint.
Error occurred when reading client request. Request is invalid.
Error occurred on server side.
{- "vehicles": [
- {
- "vehicle_id": "vehicle-1",
- "type_id": "cargo-bike",
- "start_address": {
- "location_id": "berlin",
- "lon": 13.406,
- "lat": 52.537
}, - "earliest_start": 1554804329,
- "latest_end": 1554808329,
- "max_jobs": 3
}, - {
- "vehicle_id": "vehicle-2",
- "type_id": "cargo-bike",
- "start_address": {
- "location_id": "berlin",
- "lon": 13.406,
- "lat": 52.537
}, - "earliest_start": 1554804329,
- "latest_end": 1554808329,
- "max_jobs": 3,
- "skills": [
- "physical strength"
]
}
], - "vehicle_types": [
- {
- "type_id": "cargo-bike",
- "capacity": [
- 10
], - "profile": "bike"
}
], - "services": [
- {
- "id": "s-1",
- "name": "visit-Joe",
- "address": {
- "location_id": "13.375854_52.537338",
- "lon": 13.375854,
- "lat": 52.537338
}, - "size": [
- 1
], - "time_windows": [
- {
- "earliest": 1554805329,
- "latest": 1554806329
}
]
}, - {
- "id": "s-2",
- "name": "serve-Peter",
- "address": {
- "location_id": "13.393364_52.525851",
- "lon": 13.393364,
- "lat": 52.525851
}, - "size": [
- 1
]
}, - {
- "id": "s-3",
- "name": "visit-Michael",
- "address": {
- "location_id": "13.416882_52.523543",
- "lon": 13.416882,
- "lat": 52.523543
}, - "size": [
- 1
]
}, - {
- "id": "s-4",
- "name": "do nothing",
- "address": {
- "location_id": "13.395767_52.514038",
- "lon": 13.395767,
- "lat": 52.514038
}, - "size": [
- 1
]
}
], - "shipments": [
- {
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "name": "pickup and deliver pizza to Peter",
- "priority": 1,
- "pickup": {
- "address": {
- "location_id": "13.387613_52.529961",
- "lon": 13.387613,
- "lat": 52.529961
}
}, - "delivery": {
- "address": {
- "location_id": "13.380575_52.513614",
- "lon": 13.380575,
- "lat": 52.513614
}
}, - "size": [
- 1
], - "required_skills": [
- "physical strength"
]
}
], - "objectives": [
- {
- "type": "min",
- "value": "vehicles"
}, - {
- "type": "min",
- "value": "completion_time"
}
], - "configuration": {
- "routing": {
- "calc_points": true,
- "snap_preventions": [
- "motorway",
- "trunk",
- "tunnel",
- "bridge",
- "ferry"
]
}
}
}
{- "job_id": "44886560-b584-4da5-b245-768151dacd8f"
}
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.
A response containing the solution
Error occurred on client side such as invalid input.
Requested solution could not be found.
Error occurred on server side.
curl -X GET "https://graphhopper.com/api/1/vrp/solution/job_id?key=api_key"
{- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "job_id": "d62fcadd-c84a-4298-90b5-28550125bec5",
- "status": "finished",
- "waiting_time_in_queue": 0,
- "processing_time": 459,
- "solution": {
- "costs": 438,
- "distance": 17994,
- "time": 4094,
- "transport_time": 4094,
- "completion_time": 4172,
- "max_operation_time": 2465,
- "waiting_time": 78,
- "service_duration": 0,
- "preparation_time": 0,
- "no_vehicles": 2,
- "no_unassigned": 0,
- "routes": [
- {
- "vehicle_id": "vehicle-2",
- "distance": 10618,
- "transport_time": 2465,
- "completion_time": 2465,
- "waiting_time": 0,
- "service_duration": 0,
- "preparation_time": 0,
- "points": [
- {
- "coordinates": [
- [
- 13.40608,
- 52.53701
], - [
- 13.40643,
- 52.53631
], - [
- 13.40554,
- 52.53616
], - [
- 13.4054,
- 52.53608
], - [
- 13.40445,
- 52.53513
], - [
- 13.40436,
- 52.53509
], - [
- 13.40428,
- 52.53508
], - [
- 13.40463,
- 52.53419
], - [
- 13.40451,
- 52.53419
], - [
- 13.4034,
- 52.53401
], - [
- 13.403,
- 52.53359
], - [
- 13.40291,
- 52.53354
], - [
- 13.40268,
- 52.53347
], - [
- 13.39888,
- 52.53259
], - [
- 13.39839,
- 52.53253
], - [
- 13.39812,
- 52.53251
], - [
- 13.39616,
- 52.53243
], - [
- 13.39579,
- 52.5324
], - [
- 13.38973,
- 52.53173
], - [
- 13.39163,
- 52.53025
], - [
- 13.38797,
- 52.52935
], - [
- 13.38763,
- 52.52996
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.38763,
- 52.52996
], - [
- 13.38739,
- 52.53039
], - [
- 13.38724,
- 52.53036
], - [
- 13.38464,
- 52.52929
], - [
- 13.38538,
- 52.52871
], - [
- 13.38634,
- 52.52792
], - [
- 13.38638,
- 52.52779
], - [
- 13.38657,
- 52.52763
], - [
- 13.38676,
- 52.52741
], - [
- 13.38698,
- 52.52713
], - [
- 13.38704,
- 52.52701
], - [
- 13.38753,
- 52.524
], - [
- 13.3877,
- 52.52307
], - [
- 13.3878,
- 52.52282
], - [
- 13.38788,
- 52.52252
], - [
- 13.38802,
- 52.52174
], - [
- 13.38519,
- 52.52009
], - [
- 13.38539,
- 52.5191
], - [
- 13.38548,
- 52.51852
], - [
- 13.38042,
- 52.51819
], - [
- 13.38071,
- 52.5167
], - [
- 13.38076,
- 52.51652
], - [
- 13.38084,
- 52.51634
], - [
- 13.3821,
- 52.51396
], - [
- 13.38055,
- 52.51365
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.38055,
- 52.51365
], - [
- 13.38229,
- 52.514
], - [
- 13.38363,
- 52.51429
], - [
- 13.3848,
- 52.51445
], - [
- 13.38504,
- 52.51358
], - [
- 13.39124,
- 52.51397
], - [
- 13.3911,
- 52.51488
], - [
- 13.39303,
- 52.51499
], - [
- 13.39317,
- 52.5141
], - [
- 13.39548,
- 52.51419
], - [
- 13.39571,
- 52.51421
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.39571,
- 52.51421
], - [
- 13.39695,
- 52.51434
], - [
- 13.39674,
- 52.51523
], - [
- 13.39742,
- 52.51531
], - [
- 13.39873,
- 52.51558
], - [
- 13.39846,
- 52.51599
], - [
- 13.39825,
- 52.51729
], - [
- 13.39805,
- 52.51755
], - [
- 13.39892,
- 52.51761
], - [
- 13.39917,
- 52.51764
], - [
- 13.39964,
- 52.51775
], - [
- 13.40009,
- 52.51791
], - [
- 13.40034,
- 52.51797
], - [
- 13.4021,
- 52.51864
], - [
- 13.40288,
- 52.51896
], - [
- 13.40375,
- 52.51936
], - [
- 13.40498,
- 52.52001
], - [
- 13.40463,
- 52.5203
], - [
- 13.40311,
- 52.52144
], - [
- 13.40442,
- 52.52189
], - [
- 13.40448,
- 52.52192
], - [
- 13.40451,
- 52.52195
], - [
- 13.40473,
- 52.52199
], - [
- 13.40504,
- 52.52208
], - [
- 13.40572,
- 52.52235
], - [
- 13.40687,
- 52.52294
], - [
- 13.40693,
- 52.52299
], - [
- 13.40706,
- 52.52319
], - [
- 13.40738,
- 52.52378
], - [
- 13.40787,
- 52.52443
], - [
- 13.4079,
- 52.52453
], - [
- 13.40938,
- 52.52401
], - [
- 13.40962,
- 52.52398
], - [
- 13.41001,
- 52.52395
], - [
- 13.41072,
- 52.52391
], - [
- 13.41215,
- 52.52389
], - [
- 13.41233,
- 52.52386
], - [
- 13.4131,
- 52.5235
], - [
- 13.41288,
- 52.52333
], - [
- 13.41475,
- 52.52247
], - [
- 13.41496,
- 52.52264
], - [
- 13.41523,
- 52.52251
], - [
- 13.41633,
- 52.52338
], - [
- 13.41631,
- 52.52346
], - [
- 13.41654,
- 52.52364
], - [
- 13.41684,
- 52.52351
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.41684,
- 52.52351
], - [
- 13.41654,
- 52.52364
], - [
- 13.41631,
- 52.52346
], - [
- 13.4163,
- 52.52344
], - [
- 13.41587,
- 52.52363
], - [
- 13.41572,
- 52.5235
], - [
- 13.41409,
- 52.5242
], - [
- 13.41454,
- 52.52461
], - [
- 13.41454,
- 52.52466
], - [
- 13.41358,
- 52.52508
], - [
- 13.41366,
- 52.52514
], - [
- 13.41344,
- 52.52525
], - [
- 13.4133,
- 52.52514
], - [
- 13.41316,
- 52.5252
], - [
- 13.41107,
- 52.52585
], - [
- 13.41118,
- 52.52606
], - [
- 13.41118,
- 52.52616
], - [
- 13.41095,
- 52.52664
], - [
- 13.41097,
- 52.52678
], - [
- 13.41084,
- 52.52706
], - [
- 13.41057,
- 52.52747
], - [
- 13.41028,
- 52.52809
], - [
- 13.41032,
- 52.52821
], - [
- 13.4102,
- 52.52847
], - [
- 13.40999,
- 52.52875
], - [
- 13.40984,
- 52.52905
], - [
- 13.40982,
- 52.52914
], - [
- 13.40984,
- 52.52926
], - [
- 13.4104,
- 52.52998
], - [
- 13.4105,
- 52.53001
], - [
- 13.41064,
- 52.53016
], - [
- 13.41082,
- 52.5303
], - [
- 13.41198,
- 52.53107
], - [
- 13.4122,
- 52.53128
], - [
- 13.41232,
- 52.53143
], - [
- 13.41247,
- 52.53192
], - [
- 13.41267,
- 52.53245
], - [
- 13.41275,
- 52.53259
], - [
- 13.41215,
- 52.5327
], - [
- 13.40731,
- 52.53463
], - [
- 13.40608,
- 52.53701
]
], - "type": "LineString"
}
], - "activities": [
- {
- "type": "start",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "end_time": 1554804329,
- "end_date_time": null,
- "distance": 0,
- "driving_time": 0,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_after": [
- 0
]
}, - {
- "type": "pickupShipment",
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "location_id": "13.387613_52.529961",
- "address": {
- "location_id": "13.387613_52.529961",
- "lat": 52.529961,
- "lon": 13.387613
}, - "arr_time": 1554804789,
- "arr_date_time": null,
- "end_time": 1554804789,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 2012,
- "driving_time": 460,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "deliverShipment",
- "id": "7fe77504-7df8-4497-843c-02d70b6490ce",
- "location_id": "13.380575_52.513614",
- "address": {
- "location_id": "13.380575_52.513614",
- "lat": 52.513614,
- "lon": 13.380575
}, - "arr_time": 1554805344,
- "arr_date_time": null,
- "end_time": 1554805344,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 4560,
- "driving_time": 1015,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 0
]
}, - {
- "type": "service",
- "id": "s-4",
- "location_id": "13.395767_52.514038",
- "address": {
- "location_id": "13.395767_52.514038",
- "lat": 52.514038,
- "lon": 13.395767
}, - "arr_time": 1554805632,
- "arr_date_time": null,
- "end_time": 1554805632,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 5887,
- "driving_time": 1303,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "service",
- "id": "s-3",
- "location_id": "13.416882_52.523543",
- "address": {
- "location_id": "13.416882_52.523543",
- "lat": 52.523543,
- "lon": 13.416882
}, - "arr_time": 1554806253,
- "arr_date_time": null,
- "end_time": 1554806253,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 8486,
- "driving_time": 1924,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 2
]
}, - {
- "type": "end",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "arr_time": 1554806794,
- "arr_date_time": null,
- "distance": 10618,
- "driving_time": 2465,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_before": [
- 2
]
}
]
}, - {
- "vehicle_id": "vehicle-1",
- "distance": 7376,
- "transport_time": 1629,
- "completion_time": 1707,
- "waiting_time": 78,
- "service_duration": 0,
- "preparation_time": 0,
- "points": [
- {
- "coordinates": [
- [
- 13.40608,
- 52.53701
], - [
- 13.40674,
- 52.53571
], - [
- 13.40433,
- 52.53313
], - [
- 13.40271,
- 52.53149
], - [
- 13.40246,
- 52.53121
], - [
- 13.40148,
- 52.52999
], - [
- 13.40128,
- 52.52993
], - [
- 13.40118,
- 52.52988
], - [
- 13.40133,
- 52.5296
], - [
- 13.40138,
- 52.52951
], - [
- 13.40167,
- 52.52914
], - [
- 13.40188,
- 52.52895
], - [
- 13.398,
- 52.52885
], - [
- 13.39289,
- 52.52748
], - [
- 13.39354,
- 52.5264
], - [
- 13.39358,
- 52.52628
], - [
- 13.39324,
- 52.52575
], - [
- 13.39334,
- 52.52573
], - [
- 13.39339,
- 52.52584
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.39339,
- 52.52584
], - [
- 13.3934,
- 52.52599
], - [
- 13.39358,
- 52.52628
], - [
- 13.39354,
- 52.5264
], - [
- 13.39242,
- 52.52823
], - [
- 13.39381,
- 52.52852
], - [
- 13.38973,
- 52.53173
], - [
- 13.38717,
- 52.5315
], - [
- 13.38678,
- 52.5315
], - [
- 13.38641,
- 52.53147
], - [
- 13.38617,
- 52.53143
], - [
- 13.38607,
- 52.53155
], - [
- 13.38526,
- 52.53225
], - [
- 13.38501,
- 52.53252
], - [
- 13.38316,
- 52.53418
], - [
- 13.38179,
- 52.5355
], - [
- 13.38084,
- 52.53523
], - [
- 13.38081,
- 52.53531
], - [
- 13.3795,
- 52.53677
], - [
- 13.37941,
- 52.53682
], - [
- 13.37935,
- 52.53683
], - [
- 13.37919,
- 52.53682
], - [
- 13.37617,
- 52.5361
], - [
- 13.37502,
- 52.53698
], - [
- 13.37584,
- 52.53734
]
], - "type": "LineString"
}, - {
- "coordinates": [
- [
- 13.37584,
- 52.53734
], - [
- 13.37566,
- 52.53726
], - [
- 13.37515,
- 52.53763
], - [
- 13.37644,
- 52.53841
], - [
- 13.37807,
- 52.53935
], - [
- 13.37946,
- 52.5402
], - [
- 13.3796,
- 52.54019
], - [
- 13.37984,
- 52.54021
], - [
- 13.37988,
- 52.54012
], - [
- 13.38062,
- 52.53936
], - [
- 13.38169,
- 52.53832
], - [
- 13.38236,
- 52.5377
], - [
- 13.38363,
- 52.53661
], - [
- 13.38492,
- 52.53555
], - [
- 13.38613,
- 52.53447
], - [
- 13.38757,
- 52.53338
], - [
- 13.38791,
- 52.53354
], - [
- 13.38812,
- 52.53368
], - [
- 13.38833,
- 52.53392
], - [
- 13.38977,
- 52.53518
], - [
- 13.39003,
- 52.53539
], - [
- 13.39256,
- 52.53701
], - [
- 13.39316,
- 52.53739
], - [
- 13.39327,
- 52.53744
], - [
- 13.3936,
- 52.53757
], - [
- 13.40155,
- 52.53982
], - [
- 13.40357,
- 52.53715
], - [
- 13.40372,
- 52.53719
], - [
- 13.40465,
- 52.53727
], - [
- 13.4048,
- 52.53726
], - [
- 13.4059,
- 52.53736
], - [
- 13.40608,
- 52.53701
]
], - "type": "LineString"
}
], - "activities": [
- {
- "type": "start",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "end_time": 1554804329,
- "end_date_time": null,
- "distance": 0,
- "driving_time": 0,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_after": [
- 0
]
}, - {
- "type": "service",
- "id": "s-2",
- "location_id": "13.393364_52.525851",
- "address": {
- "location_id": "13.393364_52.525851",
- "lat": 52.525851,
- "lon": 13.393364
}, - "arr_time": 1554804743,
- "arr_date_time": null,
- "end_time": 1554804743,
- "end_date_time": null,
- "waiting_time": 0,
- "distance": 1884,
- "driving_time": 414,
- "preparation_time": 0,
- "load_before": [
- 0
], - "load_after": [
- 1
]
}, - {
- "type": "service",
- "id": "s-1",
- "location_id": "13.375854_52.537338",
- "address": {
- "location_id": "13.375854_52.537338",
- "lat": 52.537338,
- "lon": 13.375854
}, - "arr_time": 1554805251,
- "arr_date_time": null,
- "end_time": 1554805329,
- "end_date_time": null,
- "waiting_time": 78,
- "distance": 4205,
- "driving_time": 922,
- "preparation_time": 0,
- "load_before": [
- 1
], - "load_after": [
- 2
]
}, - {
- "type": "end",
- "location_id": "berlin",
- "address": {
- "location_id": "berlin",
- "lat": 52.537,
- "lon": 13.406
}, - "arr_time": 1554806036,
- "arr_date_time": null,
- "distance": 7376,
- "driving_time": 1629,
- "preparation_time": 0,
- "waiting_time": 0,
- "load_before": [
- 2
]
}
]
}
], - "unassigned": {
- "services": [ ],
- "shipments": [ ],
- "breaks": [ ],
- "details": [ ]
}
}
}
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.
custom_model
Feature to modify existing vehicle profiles. See some examples here.For the GET request you specify the parameters in the URL and can try it directly in every browser.
However, it has some disadvantages when using many points (URL length limit) and the custom_model
Feature cannot be used.
Therefore, our recommended endpoint is the POST route endpoint.
profile | string (VehicleProfileId) Default: "car" The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
point required | Array of strings The points for which the route should be calculated. Format: Example: point=51.131,12.414&point=48.224,3.867 |
point_hint | Array of strings The |
snap_prevention | Array of strings Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the |
curbside | Array of strings Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap. |
locale | string Default: "en" The locale of the resulting turn instructions. E.g. |
elevation | boolean Default: false If |
details | Array of strings Optional parameter. The following path details are available: |
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 |
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 |
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 |
ch.disable | boolean Default: false Use this parameter in combination with one or more parameters from below. |
heading | Array of integers <int32> Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
This parameter also influences the tour generated with |
heading_penalty | integer <int32> Default: 300 Time penalty in seconds for not obeying a specified heading. Requires |
pass_through | boolean Default: false If |
algorithm | string Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing:
With |
round_trip.distance | integer <int32> Default: 10000 If |
round_trip.seed | integer <int64> If |
alternative_route.max_paths | integer <int32> Default: 2 If |
alternative_route.max_weight_factor | number Default: 1.4 If |
alternative_route.max_share_factor | number Default: 0.6 If |
Routing Result
Your request is not valid. For example, you specified too few or too many points.
Authentication necessary
API limit reached.
Internal server error. We get notified automatically and fix this asap.
curl "https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&profile=car&locale=de&calc_points=false&key=api_key"
{- "hints": {
- "visited_nodes.sum": 58,
- "visited_nodes.average": 58
}, - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "took": 2
}, - "paths": [
- {
- "distance": 1791.011,
- "weight": 307.852443,
- "time": 370962,
- "transfers": 0,
- "points_encoded": false,
- "bbox": [
- 11.539424,
- 48.118343,
- 11.558901,
- 48.122364
], - "points": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.540387,
- 48.118368
], - [
- 11.54061,
- 48.118356
], - [
- 11.541941,
- 48.118409
], - [
- 11.543696,
- 48.118344
], - [
- 11.547167,
- 48.118343
], - [
- 11.548478,
- 48.118366
], - [
- 11.548487,
- 48.119329
], - [
- 11.548807,
- 48.119328
], - [
- 11.549408,
- 48.119366
], - [
- 11.550349,
- 48.119508
], - [
- 11.550441,
- 48.119473
], - [
- 11.551109,
- 48.119467
], - [
- 11.551553,
- 48.119445
], - [
- 11.551748,
- 48.119398
], - [
- 11.552087,
- 48.119475
], - [
- 11.552236,
- 48.119542
], - [
- 11.552353,
- 48.119635
], - [
- 11.553853,
- 48.121136
], - [
- 11.555448,
- 48.12039
], - [
- 11.555797,
- 48.120206
], - [
- 11.55632,
- 48.120592
], - [
- 11.556716,
- 48.120919
], - [
- 11.557326,
- 48.121345
], - [
- 11.558901,
- 48.122364
]
]
}, - "instructions": [
- {
- "distance": 672.954,
- "heading": 89.04,
- "sign": 0,
- "interval": [
- 0,
- 6
], - "text": "Continue onto Lindenschmitstraße",
- "time": 144703,
- "street_name": "Lindenschmitstraße"
}, - {
- "distance": 107.145,
- "sign": -2,
- "interval": [
- 6,
- 7
], - "text": "Turn left",
- "time": 22675,
- "street_name": ""
}, - {
- "distance": 140.169,
- "sign": 2,
- "interval": [
- 7,
- 10
], - "text": "Turn right onto Oberländerstraße",
- "time": 28032,
- "street_name": "Oberländerstraße"
}, - {
- "distance": 360.232,
- "sign": 1,
- "interval": [
- 10,
- 18
], - "text": "Turn slight right",
- "time": 72677,
- "street_name": ""
}, - {
- "distance": 177.621,
- "sign": 2,
- "interval": [
- 18,
- 20
], - "text": "Turn right onto Thalkirchner Straße",
- "time": 35524,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 332.89,
- "sign": -2,
- "interval": [
- 20,
- 24
], - "text": "Turn left onto Thalkirchner Straße",
- "time": 67351,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 0,
- "sign": 4,
- "last_heading": 45.67046584987792,
- "interval": [
- 24,
- 24
], - "text": "Arrive at destination",
- "time": 0,
- "street_name": ""
}
], - "legs": [ ],
- "details": { },
- "ascend": 6.3294677734375,
- "descend": 25.0579833984375,
- "snapped_waypoints": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.558901,
- 48.122364
]
]
}
}
]
}
To do a request you send JSON data.
See the GET endpoint for an alternative query method which is slightly simpler to get started but has some disadvantages.
Please note that in contrast to the GET endpoint, points are specified in the order of [longitude, latitude]
and some parameter names use the plural.
For example the string point=10,11&point=20,22
will be converted to the points
array (plural):
{ "points": [[11,10], [22,20]] }
So this points
array uses a format similar to GeoJson.
Example:
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]],"profile":"car"}'
profile | string (VehicleProfileId) The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
points | Array of numbers The points for the route in an array of |
point_hints | Array of strings Optional parameter. Specifies a hint for each point in the |
snap_preventions | Array of strings Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the |
curbsides | Array of strings Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicle profiles and OpenStreetMap. |
locale | string Default: "en" The locale of the resulting turn instructions. E.g. |
elevation | boolean Default: false If |
details | Array of strings Optional parameter. The following path details are available: |
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 |
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 |
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 |
ch.disable | boolean Default: false Use this parameter in combination with one or more parameters from below. |
object (CustomModel) The custom_model modifies the routing behaviour of the specified profile. See the detailed documentation.
Below is a complete request example in Berlin that limits all speeds to 100km/h, excludes motorways and makes shorter routes a bit more likely than the default due to a higher distance_influence.
Note that it also includes the
| |
headings | Array of integers <int32> Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
This parameter also influences the tour generated with |
heading_penalty | integer <int32> Default: 300 Time penalty in seconds for not obeying a specified heading. Requires |
pass_through | boolean Default: false If |
algorithm | string Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing:
With |
round_trip.distance | integer <int32> Default: 10000 If |
round_trip.seed | integer <int64> If |
alternative_route.max_paths | integer <int32> Default: 2 If |
alternative_route.max_weight_factor | number Default: 1.4 If |
alternative_route.max_share_factor | number Default: 0.6 If |
Routing Result
Your request is not valid. For example, you specified too few or too many points.
Authentication necessary
API limit reached.
Internal server error. We get notified automatically and fix this asap.
{- "profile": "bike",
- "points": [
- [
- 11.539421,
- 48.118477
], - [
- 11.559023,
- 48.12228
]
], - "point_hints": [
- "Lindenschmitstraße",
- "Thalkirchener Str."
], - "snap_preventions": [
- "motorway",
- "ferry",
- "tunnel"
], - "details": [
- "road_class",
- "surface"
]
}
{- "hints": {
- "visited_nodes.sum": 58,
- "visited_nodes.average": 58
}, - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "took": 2
}, - "paths": [
- {
- "distance": 1791.011,
- "weight": 307.852443,
- "time": 370962,
- "transfers": 0,
- "points_encoded": false,
- "bbox": [
- 11.539424,
- 48.118343,
- 11.558901,
- 48.122364
], - "points": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.540387,
- 48.118368
], - [
- 11.54061,
- 48.118356
], - [
- 11.541941,
- 48.118409
], - [
- 11.543696,
- 48.118344
], - [
- 11.547167,
- 48.118343
], - [
- 11.548478,
- 48.118366
], - [
- 11.548487,
- 48.119329
], - [
- 11.548807,
- 48.119328
], - [
- 11.549408,
- 48.119366
], - [
- 11.550349,
- 48.119508
], - [
- 11.550441,
- 48.119473
], - [
- 11.551109,
- 48.119467
], - [
- 11.551553,
- 48.119445
], - [
- 11.551748,
- 48.119398
], - [
- 11.552087,
- 48.119475
], - [
- 11.552236,
- 48.119542
], - [
- 11.552353,
- 48.119635
], - [
- 11.553853,
- 48.121136
], - [
- 11.555448,
- 48.12039
], - [
- 11.555797,
- 48.120206
], - [
- 11.55632,
- 48.120592
], - [
- 11.556716,
- 48.120919
], - [
- 11.557326,
- 48.121345
], - [
- 11.558901,
- 48.122364
]
]
}, - "instructions": [
- {
- "distance": 672.954,
- "heading": 89.04,
- "sign": 0,
- "interval": [
- 0,
- 6
], - "text": "Continue onto Lindenschmitstraße",
- "time": 144703,
- "street_name": "Lindenschmitstraße"
}, - {
- "distance": 107.145,
- "sign": -2,
- "interval": [
- 6,
- 7
], - "text": "Turn left",
- "time": 22675,
- "street_name": ""
}, - {
- "distance": 140.169,
- "sign": 2,
- "interval": [
- 7,
- 10
], - "text": "Turn right onto Oberländerstraße",
- "time": 28032,
- "street_name": "Oberländerstraße"
}, - {
- "distance": 360.232,
- "sign": 1,
- "interval": [
- 10,
- 18
], - "text": "Turn slight right",
- "time": 72677,
- "street_name": ""
}, - {
- "distance": 177.621,
- "sign": 2,
- "interval": [
- 18,
- 20
], - "text": "Turn right onto Thalkirchner Straße",
- "time": 35524,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 332.89,
- "sign": -2,
- "interval": [
- 20,
- 24
], - "text": "Turn left onto Thalkirchner Straße",
- "time": 67351,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 0,
- "sign": 4,
- "last_heading": 45.67046584987792,
- "interval": [
- 24,
- 24
], - "text": "Arrive at destination",
- "time": 0,
- "street_name": ""
}
], - "legs": [ ],
- "details": { },
- "ascend": 6.3294677734375,
- "descend": 25.0579833984375,
- "snapped_waypoints": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.558901,
- 48.122364
]
]
}
}
]
}
For N origins and M destinations, compute routes from all origins to all destinations and output the result as a matrix of travel times and/or distances.
This includes the common cases of routes from one origin to many destinations, or from many origins to one destination.
profile | string (VehicleProfileId) The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
from_points | Array of numbers The origin points for the routes in an array of |
to_points | Array of numbers The destination points for the routes in an array of |
from_point_hints | Array of strings See |
to_point_hints | Array of strings See |
snap_preventions | Array of strings See |
from_curbsides | Array of strings See |
to_curbsides | Array of strings See |
out_arrays | Array of strings Specifies which matrices should be included in the response. Specify one or more of the following options |
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 |
Matrix API response
{- "from_points": [
- [
- -0.11379003524780275,
- 51.53664617804063
], - [
- -0.10866165161132814,
- 51.538621486960956
], - [
- -0.11059284210205078,
- 51.53245503603458
]
], - "to_points": [
- [
- -0.09576559066772462,
- 51.512882367963456
], - [
- -0.08797645568847656,
- 51.51317615367198
]
], - "from_point_hints": [
- "Copenhagen Street",
- "Richmond Avenue",
- "White Lion Street"
], - "to_point_hints": [
- "Cannon",
- "Cornhill"
], - "out_arrays": [
- "weights",
- "times",
- "distances"
], - "vehicle": "car"
}
{- "distances": [
- [
- 0,
- 97653,
- 48887
], - [
- 97426,
- 0,
- 121035
], - [
- 49006,
- 121049,
- 0
]
], - "times": [
- [
- 0,
- 4197,
- 2994
], - [
- 4192,
- 0,
- 6074
], - [
- 3006,
- 6062,
- 0
]
], - "weights": [
- [
- 0,
- 5662.551,
- 3727.147
], - [
- 5653.807,
- 0,
- 7889.653
], - [
- 3741.528,
- 7878.365,
- 0
]
], - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
]
}
}
For N origins and M destinations, compute routes from all origins to all destinations and output the result as a matrix of travel times and/or distances.
This includes the common cases of routes from one origin to many destinations, or from many origins to one destination.
profile | string (VehicleProfileId) Default: "car" The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
point | Array of strings Specify multiple points in |
from_point | Array of strings The origin points for the routes in |
to_point | Array of strings The destination points for the routes in |
point_hint | Array of strings Optional parameter. Specifies a hint for each |
from_point_hint | Array of strings For the from_point parameter. See point_hint |
to_point_hint | Array of strings For the to_point parameter. See point_hint |
snap_prevention | Array of strings Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the |
curbside | Array of strings Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap. |
from_curbside | Array of strings Curbside setting for the from_point parameter. See curbside. |
to_curbside | Array of strings Curbside setting for the to_point parameter. See curbside. |
out_array | Array of strings Specifies which arrays should be included in the response. Specify one or more of the following options 'weights', 'times', 'distances'. To specify more than one array use e.g. out_array=times&out_array=distances. The units of the entries of distances are meters, of times are seconds and of weights is arbitrary and it can differ for different vehicles or versions of this API. |
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 |
Matrix API response
curl "https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747375&point=50.118817,11.983337&type=json&profile=car&out_array=weights&out_array=times&out_array=distances&key=api_key"
{- "distances": [
- [
- 0,
- 97653,
- 48887
], - [
- 97426,
- 0,
- 121035
], - [
- 49006,
- 121049,
- 0
]
], - "times": [
- [
- 0,
- 4197,
- 2994
], - [
- 4192,
- 0,
- 6074
], - [
- 3006,
- 6062,
- 0
]
], - "weights": [
- [
- 0,
- 5662.551,
- 3727.147
], - [
- 5653.807,
- 0,
- 7889.653
], - [
- 3741.528,
- 7878.365,
- 0
]
], - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
]
}
}
An alternate endpoint for computing a large matrix asynchronously, where a request against the regular endpoint would result in a timeout.
The request format is the same, but instead of the result, you are given a job identification number that you can use to retrieve the result once it is available.
In most cases, prefer the regular endpoints.
Here are some full examples via curl:
$ 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:
$ 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
:
$ 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.:
{"message":"Cannot find from_points: 1"}
And the optional hints
array.
profile | string (VehicleProfileId) The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
from_points | Array of numbers The origin points for the routes in an array of |
to_points | Array of numbers The destination points for the routes in an array of |
from_point_hints | Array of strings See |
to_point_hints | Array of strings See |
snap_preventions | Array of strings See |
from_curbsides | Array of strings See |
to_curbsides | Array of strings See |
out_arrays | Array of strings Specifies which matrices should be included in the response. Specify one or more of the following options |
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 |
A jobId you can use to retrieve your solution from the server.
{- "from_points": [
- [
- -0.11379003524780275,
- 51.53664617804063
], - [
- -0.10866165161132814,
- 51.538621486960956
], - [
- -0.11059284210205078,
- 51.53245503603458
]
], - "to_points": [
- [
- -0.09576559066772462,
- 51.512882367963456
], - [
- -0.08797645568847656,
- 51.51317615367198
]
], - "from_point_hints": [
- "Copenhagen Street",
- "Richmond Avenue",
- "White Lion Street"
], - "to_point_hints": [
- "Cannon",
- "Cornhill"
], - "out_arrays": [
- "weights",
- "times",
- "distances"
], - "vehicle": "car"
}
{- "job_id": "44886560-b584-4da5-b245-768151dacd8f"
}
A response containing the matrix
{- "solution": {
- "distances": [
- [
- 0,
- 97653,
- 48887
], - [
- 97426,
- 0,
- 121035
], - [
- 49006,
- 121049,
- 0
]
], - "times": [
- [
- 0,
- 4197,
- 2994
], - [
- 4192,
- 0,
- 6074
], - [
- 3006,
- 6062,
- 0
]
], - "weights": [
- [
- 0,
- 5662.551,
- 3727.147
], - [
- 5653.807,
- 0,
- 7889.653
], - [
- 3741.528,
- 7878.365,
- 0
]
], - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
]
}
}
}
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.
q | string A textual description of the address you are looking for. Required for forward geocoding. Note that the |
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. |
limit | integer <int32> Default: 5 Specify the maximum number of results to return |
reverse | boolean Default: false It is |
debug | boolean Default: false If |
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 The credit costs can be different for all providers - see here for more information about it. Currently, only the default provider and gisgraphy support autocompletion of partial search strings. All providers support normal "forward" geocoding and reverse geocoding via Default (
|
An array found locations
curl "https://graphhopper.com/api/1/geocode?q=berlin&locale=de&key=api_key"
{- "hits": [
- {
- "osm_id": 240109189,
- "osm_type": "N",
- "country": "Deutschland",
- "osm_key": "place",
- "city": "Berlin",
- "osm_value": "city",
- "postcode": "10117",
- "name": "Berlin",
- "point": {
- "lng": 13.3888599,
- "lat": 52.5170365
}
}, - {
- "osm_id": 62422,
- "osm_type": "R",
- "extent": [
- 13.088345,
- 52.6755087,
- 13.7611609,
- 52.33826
], - "country": "Deutschland",
- "osm_key": "place",
- "osm_value": "city",
- "name": "Berlin",
- "point": {
- "lng": 13.4385964,
- "lat": 52.5198535
}
}, - {
- "osm_id": 120456814,
- "osm_type": "W",
- "extent": [
- 13.3906703,
- 52.5200704,
- 13.3948873,
- 52.5175007
], - "country": "Deutschland",
- "osm_key": "amenity",
- "city": "Berlin",
- "street": "Dorotheenstraße",
- "osm_value": "university",
- "postcode": "10117",
- "name": "Humboldt-Universität zu Berlin",
- "point": {
- "lng": 13.393560493637775,
- "lat": 52.51875685
}
}, - {
- "osm_id": 6647,
- "osm_type": "R",
- "extent": [
- 13.3924346,
- 52.5191829,
- 13.3948768,
- 52.517526
], - "country": "Deutschland",
- "osm_key": "building",
- "housenumber": "6",
- "city": "Berlin",
- "street": "Unter den Linden",
- "osm_value": "yes",
- "postcode": "10117",
- "name": "Humboldt-Universität zu Berlin",
- "point": {
- "lng": 13.392908021752554,
- "lat": 52.51840935
}
}, - {
- "osm_id": 38862723,
- "osm_type": "W",
- "extent": [
- 13.2364563,
- 52.5161915,
- 13.2433375,
- 52.5129557
], - "country": "Deutschland",
- "osm_key": "leisure",
- "housenumber": "3",
- "city": "Berlin",
- "street": "Olympischer Platz",
- "osm_value": "stadium",
- "postcode": "14053",
- "name": "Olympiastadion Berlin",
- "point": {
- "lng": 13.239776301622072,
- "lat": 52.5147077
}
}, - {
- "osm_id": 583306346,
- "osm_type": "W",
- "extent": [
- 13.3739245,
- 52.528547,
- 13.3818019,
- 52.5229778
], - "country": "Deutschland",
- "osm_key": "amenity",
- "city": "Berlin",
- "street": "Hufelandweg",
- "osm_value": "hospital",
- "postcode": "10117",
- "name": "Charité Universitätsmedizin Berlin",
- "point": {
- "lng": 13.377739577932736,
- "lat": 52.52585125
}
}, - {
- "osm_id": 180594,
- "osm_type": "R",
- "extent": [
- 13.3906159,
- 52.5190301,
- 13.3923847,
- 52.5174089
], - "country": "Deutschland",
- "osm_key": "amenity",
- "housenumber": "8",
- "city": "Berlin",
- "street": "Unter den Linden",
- "osm_value": "library",
- "postcode": "10117",
- "name": "Staatsbibliothek zu Berlin",
- "point": {
- "lng": 13.391516532100738,
- "lat": 52.5182233
}
}, - {
- "osm_id": 3856100103,
- "osm_type": "N",
- "country": "Deutschland",
- "osm_key": "railway",
- "city": "Berlin",
- "street": "Washingtonplatz",
- "osm_value": "station",
- "postcode": "10557",
- "name": "Berlin Hauptbahnhof",
- "point": {
- "lng": 13.3696614,
- "lat": 52.5249451
}
}, - {
- "osm_id": 1078631331,
- "osm_type": "N",
- "country": "Deutschland",
- "osm_key": "historic",
- "city": "Berlin",
- "street": "Gertrud-Kolmar-Straße",
- "osm_value": "battlefield",
- "postcode": "10117",
- "name": "Schlacht um Berlin",
- "point": {
- "lng": 13.3814231,
- "lat": 52.5127537
}
}, - {
- "osm_id": 1154556,
- "osm_type": "R",
- "extent": [
- 13.3807495,
- 52.5083344,
- 13.3822459,
- 52.5074359
], - "country": "Deutschland",
- "osm_key": "office",
- "housenumber": "5",
- "city": "Berlin",
- "street": "Niederkirchnerstraße",
- "osm_value": "government",
- "postcode": "10117",
- "name": "Abgeordnetenhaus von Berlin",
- "point": {
- "lng": 13.381504320489928,
- "lat": 52.50786655
}
}
], - "took": 37
}
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.
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:
See the clients section in the main documentation, and our API explorer.
point required | string Specify the start coordinate |
time_limit | integer <int32> Default: 600 Specify which time the vehicle should travel. In seconds. |
distance_limit | integer <int32> Specify which distance the vehicle should travel. In meters. |
profile | string (VehicleProfileId) Default: "car" The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
buckets | integer <int32> Default: 1 Number by which to divide the given |
reverse_flow | boolean Default: false If |
Isochrone Result
{- "polygons": [
- {
- "properties": {
- "bucket": 0
}, - "type": "Feature",
- "geometry": {
- "type": "Polygon",
- "coordinates": [
- [
- 13.351851,
- 52.51345
], - [
- 13.350402,
- 52.516949
], - [
- 13.352598,
- 52.522252
], - [
- 13.351851,
- 52.51345
]
]
}
}
]
}
You get an example response for a GPX via:
curl -XPOST -H "Content-Type: application/gpx+xml" "https://graphhopper.com/api/1/match?profile=car&key=[YOUR_KEY]" --data @/path/to/some.gpx
A minimal working GPX file looks like
<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>
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 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.
gps_accuracy | integer Specify the precision of a point, in meter |
profile | string (VehicleProfileId) Default: "car" The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values. |
locale | string Default: "en" The locale of the resulting turn instructions. E.g. |
elevation | boolean Default: false If |
details | Array of strings Optional parameter. The following path details are available: |
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 |
Map matching result
curl -XPOST -H "Content-Type: application/gpx+xml" "https://graphhopper.com/api/1/match?profile=car&key=[YOUR_KEY]" -d ' <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>'
{- "hints": {
- "visited_nodes.sum": 58,
- "visited_nodes.average": 58
}, - "info": {
- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "took": 2
}, - "paths": [
- {
- "distance": 1791.011,
- "weight": 307.852443,
- "time": 370962,
- "transfers": 0,
- "points_encoded": false,
- "bbox": [
- 11.539424,
- 48.118343,
- 11.558901,
- 48.122364
], - "points": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.540387,
- 48.118368
], - [
- 11.54061,
- 48.118356
], - [
- 11.541941,
- 48.118409
], - [
- 11.543696,
- 48.118344
], - [
- 11.547167,
- 48.118343
], - [
- 11.548478,
- 48.118366
], - [
- 11.548487,
- 48.119329
], - [
- 11.548807,
- 48.119328
], - [
- 11.549408,
- 48.119366
], - [
- 11.550349,
- 48.119508
], - [
- 11.550441,
- 48.119473
], - [
- 11.551109,
- 48.119467
], - [
- 11.551553,
- 48.119445
], - [
- 11.551748,
- 48.119398
], - [
- 11.552087,
- 48.119475
], - [
- 11.552236,
- 48.119542
], - [
- 11.552353,
- 48.119635
], - [
- 11.553853,
- 48.121136
], - [
- 11.555448,
- 48.12039
], - [
- 11.555797,
- 48.120206
], - [
- 11.55632,
- 48.120592
], - [
- 11.556716,
- 48.120919
], - [
- 11.557326,
- 48.121345
], - [
- 11.558901,
- 48.122364
]
]
}, - "instructions": [
- {
- "distance": 672.954,
- "heading": 89.04,
- "sign": 0,
- "interval": [
- 0,
- 6
], - "text": "Continue onto Lindenschmitstraße",
- "time": 144703,
- "street_name": "Lindenschmitstraße"
}, - {
- "distance": 107.145,
- "sign": -2,
- "interval": [
- 6,
- 7
], - "text": "Turn left",
- "time": 22675,
- "street_name": ""
}, - {
- "distance": 140.169,
- "sign": 2,
- "interval": [
- 7,
- 10
], - "text": "Turn right onto Oberländerstraße",
- "time": 28032,
- "street_name": "Oberländerstraße"
}, - {
- "distance": 360.232,
- "sign": 1,
- "interval": [
- 10,
- 18
], - "text": "Turn slight right",
- "time": 72677,
- "street_name": ""
}, - {
- "distance": 177.621,
- "sign": 2,
- "interval": [
- 18,
- 20
], - "text": "Turn right onto Thalkirchner Straße",
- "time": 35524,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 332.89,
- "sign": -2,
- "interval": [
- 20,
- 24
], - "text": "Turn left onto Thalkirchner Straße",
- "time": 67351,
- "street_name": "Thalkirchner Straße"
}, - {
- "distance": 0,
- "sign": 4,
- "last_heading": 45.67046584987792,
- "interval": [
- 24,
- 24
], - "text": "Arrive at destination",
- "time": 0,
- "street_name": ""
}
], - "legs": [ ],
- "details": { },
- "ascend": 6.3294677734375,
- "descend": 25.0579833984375,
- "snapped_waypoints": {
- "type": "LineString",
- "coordinates": [
- [
- 11.539424,
- 48.118352
], - [
- 11.558901,
- 48.122364
]
]
}
}
]
}
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 the Cluster API 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.
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.
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.
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.
Request object that contains the problem to be solved
object (ClusterConfiguration) | |
Array of objects (Clusters) | |
Array of objects (ClusterCustomer) |
A response containing the solution
Error occurred when reading the request. Request is invalid.
Error occurred on server side.
{- "configuration": {
- "response_type": "json",
- "routing": {
- "profile": "car",
- "cost_per_second": 1,
- "cost_per_meter": 0
}, - "clustering": {
- "num_clusters": 10,
- "max_quantity": 50,
- "min_quantity": 30
}
}, - "clusters": [
- {
- "name": "GraphHopper GmbH",
- "center": {
- "lon": 11.53941,
- "lat": 48.118434,
- "street_hint": "Lindenschmitstraße 52"
}, - "min_quantity": 10,
- "max_quantity": 10
}
], - "customers": [
- {
- "id": "GraphHopper GmbH",
- "address": {
- "lon": 11.53941,
- "lat": 48.118434,
- "street_hint": "Lindenschmitstraße 52"
}, - "quantity": 10
}
]
}
{- "copyrights": [
- "GraphHopper",
- "OpenStreetMap contributors"
], - "status": "finished",
- "waiting_time_in_queue": 0,
- "processing_time": 4900,
- "clusters": [
- {
- "quantity": 40,
- "ids": [
- "GraphHopper GmbH"
]
}
]
}
Prefer the synchronous endpoint and use this Batch Cluster endpoint for long running problems only. The work flow is asynchronous:
https://graphhopper.com/api/1/cluster/calculate?key=<your_key>
and fetch the job_id.status=finished
. Do this with a GET request
towards https://graphhopper.com/api/1/cluster/solution/<job_id>?key=<your_key>
.Request object that contains the problem to be solved
object (ClusterConfiguration) | |
Array of objects (Clusters) | |
Array of objects (ClusterCustomer) |
A jobId you can use to retrieve your solution from the server - see solution endpoint.
Error occurred when reading client request. Request is invalid.
Error occurred on server side.