-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenapi.yml
5258 lines (5258 loc) · 225 KB
/
openapi.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"openapi": "3.0.0",
"info": {
"title": "GraphHopper Directions API",
"description": "\nWith the [GraphHopper Directions API](https://www.graphhopper.com/products/) you can integrate A-to-B route planning, turn-by-turn navigation,\nroute optimization, isochrone calculations and other tools in your application.\n\nThe GraphHopper Directions API consists of the following RESTful web services:\n\n * [Routing API](#tag/Routing-API),\n * [Route Optimization API](#tag/Route-Optimization-API),\n * [Isochrone API](#tag/Isochrone-API),\n * [Map Matching API](#tag/Map-Matching-API),\n * [Matrix API](#tag/Matrix-API),\n * [Geocoding API](#tag/Geocoding-API) and\n * [Cluster API](#tag/Cluster-API).\n\n# Explore our APIs\n\n## Get started\n\n1. [Sign up for GraphHopper](https://support.graphhopper.com/a/solutions/articles/44001976025)\n2. [Create an API key](https://support.graphhopper.com/a/solutions/articles/44001976027)\n\nEach API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials.\n\nIn addition, for each API there are specific sample requests that you can send via Insomnia or Postman to see what the requests and responses look like.\n\n## Insomnia\n\nTo explore our APIs with [Insomnia](https://insomnia.rest/), follow these steps:\n\n1. Open Insomnia and Import [our workspace](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/GraphHopper-Direction-API-Insomnia.json).\n2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your workspace: Manage Environments -> Base Environment -> `\"api_key\": your API key`\n3. Start exploring\n\n\n\n## Postman\n\nTo explore our APIs with [Postman](https://www.getpostman.com/), follow these steps:\n\n1. Import our [request collections](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_collection.json) as well as our [environment file](https://raw.githubusercontent.com/graphhopper/directions-api-doc/master/web/restclients/graphhopper_directions_api.postman_environment.json).\n2. Specify [your API key](https://graphhopper.com/dashboard/#/register) in your environment: `\"api_key\": your API key`\n3. Start exploring\n\n\n\n## API Client Libraries\n\nTo speed up development and make coding easier, we offer the following client libraries:\n\n * [JavaScript client](https://github.com/graphhopper/directions-api-js-client) - try the [live examples](https://graphhopper.com/api/1/examples/)\n * [Others](https://github.com/graphhopper/directions-api-clients) like C#, Ruby, PHP, Python, ... automatically created for the Route Optimization API\n\n### Bandwidth reduction\n\nIf you create your own client, make sure it supports http/2 and gzipped responses for best speed.\n\nIf you use the Matrix or Route Optimization API and want to solve large problems, we recommend you to reduce bandwidth\nby [compressing your POST request](https://gist.github.com/karussell/82851e303ea7b3459b2dea01f18949f4)\nand specifying the header as follows: `Content-Encoding: gzip`.\n\n## Contact Us\n\nIf you have problems or questions, please read the following information:\n\n- [FAQ](https://graphhopper.com/api/1/docs/FAQ/)\n- [Public forum](https://discuss.graphhopper.com/c/directions-api)\n- [Contact us](https://www.graphhopper.com/contact-form/)\n\nTo stay informed about the latest developments, you can\n\n- follow us on [twitter](https://twitter.com/graphhopper/),\n- read [our blog](https://graphhopper.com/blog/),\n- watch [our documentation](https://github.com/graphhopper/directions-api-doc),\n- sign up for our newsletter or\n- [our forum](https://discuss.graphhopper.com/c/directions-api).\n\nSelect the channel you like the most.\n\n\n# Map Data and Routing Profiles\n\nCurrently, our main data source is [OpenStreetMap](https://www.openstreetmap.org). We also integrated other network data providers.\nThis chapter gives an overview about the options you have.\n\n## OpenStreetMap\n\n#### Geographical Coverage\n\n[OpenStreetMap](https://www.openstreetmap.org) covers the whole world. If you want to see for yourself if we can provide data suitable for your region,\nplease visit [GraphHopper Maps](https://graphhopper.com/maps/).\nYou can edit and modify OpenStreetMap data if you find that important information is missing, e.g. a weight limit for a bridge.\n[Here](https://wiki.openstreetmap.org/wiki/Beginners%27_guide) 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.\n\n#### Supported Vehicle Profiles\n\nThe Routing, Matrix and Route Optimization APIs support the following vehicle profiles:\n\nName | Description | Restrictions | Icon\n-----------|:----------------------|:--------------------------|:---------------------------------------------------------\ncar | Car mode | car access | \nsmall_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | \ntruck | Truck like a MAN or Mercedes-Benz Actros | height=3.7m, width=2.6+0.5m, length=12m, weight=13000 + 13000 kg, hgv=yes, 3 Axes | \nscooter | Moped mode | Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h | \nfoot | Pedestrian or walking without dangerous [SAC-scales](https://wiki.openstreetmap.org/wiki/Key:sac_scale) | foot access | \nhike | 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 | \nbike | Trekking bike avoiding hills | bike access | \nmtb | Mountainbike | bike access | \nracingbike| Bike preferring roads | bike access | \n\nPlease note:\n\n * all motor vehicles (`car`, `small_truck`, `truck` and `scooter`) support turn restrictions via `turn_costs=true`\n * the free package supports only the vehicle profiles `car`, `bike` or `foot`\n * up to 2 different vehicle profiles can be used in a single optimization request. The number of vehicles is unaffected and depends on your subscription.\n * we offer custom vehicle profiles with different properties, different speed profiles or different access options. To find out more about custom profiles, please [contact us](https://www.graphhopper.com/contact-form/).\n * a sophisticated `motorcycle` profile is available up on request. It is powered by the [Kurviger](https://kurviger.de/en) Routing API and favors curves and slopes while avoiding cities and highways.\n \n## TomTom\n\nIf you want to include traffic, you can purchase the TomTom Add-on.\nThis Add-on only uses TomTom's road network and historical traffic information.\nLive traffic is not yet considered. If you are interested to learn how we consider traffic information, we recommend that you read [this article](https://www.graphhopper.com/blog/2017/11/06/time-dependent-optimization/).\n\nPlease note the following:\n\n * Currently we only offer this for our [Route Optimization API](#tag/Route-Optimization-API).\n * In addition to our terms, you need to accept TomTom's [End User License Aggreement](https://www.graphhopper.com/tomtom-end-user-license-agreement/).\n * We do *not* use TomTom's web services. We only use their data with our software.\n \n[Contact us](https://www.graphhopper.com/contact-form/) for more details.\n\n#### Geographical Coverage\n\nWe offer\n\n- Europe including Russia\n- North, Central and South America\n- Saudi Arabia\n- United Arab Emirates\n- South Africa\n- Australia\n\n#### Supported Vehicle Profiles\n\nName | Description | Restrictions | Icon\n-----------|:----------------------|:--------------------------|:---------------------------------------------------------\ncar | Car mode | car access | \nsmall_truck| Small truck like a Mercedes Sprinter, Ford Transit or Iveco Daily | height=2.7m, width=2+0.4m, length=5.5m, weight=2080+1400 kg | \n",
"version": "1.0.0",
"termsOfService": "https://www.graphhopper.com/terms/",
"contact": {
"name": "API Support",
"email": "[email protected]",
"url": "https://www.graphhopper.com/"
},
"x-logo": {
"url": "graphhopper-logo.svg",
"altText": "GraphHopper"
}
},
"servers": [
{
"url": "https://graphhopper.com/api/1"
}
],
"tags": [
{
"name": "Route Optimization API",
"description": "\n## Quickstart\n\nThe Route Optimization API can be used to solve [traveling salesman](https://en.wikipedia.org/wiki/Travelling_salesman_problem) or [vehicle routing problems](https://en.wikipedia.org/wiki/Vehicle_routing_problem).\nSolve your first problem by following these steps. If you already have a GraphHopper account, start with step 2.\n\n1. [Sign up for GraphHopper](https://support.graphhopper.com/a/solutions/articles/44001976025)\n2. [Create an API key](https://support.graphhopper.com/a/solutions/articles/44001976027)\n3. Download [simple traveling salesman problem](https://gist.github.com/oblonski/fb2f2be534c3ebe7bebaa72151194182) and save it in a local folder\n4. Open your command line, go to that local folder and use cURL ([What is cURL?](https://de.wikipedia.org/wiki/CURL)) as follows:\n\n ```\n curl -X POST -H \"Content-Type: application/json\" \"https://graphhopper.com/api/1/vrp?key=YOUR_CREATED_API_KEY\" --data \"@tsp.json\"\n ```\n\nAlternatively, you can use our Editor to explore that API:\n\n1. Login to your GraphHopper account\n2. Go to **Editor**\n3. Click the **Optimize** button to solve your first problem\n4. Analyze the solution on the **Map** or as raw **JSON Output**\n\nIf you have successfully solved the first problem, we recommend this tutorial - [Getting Started with the Optimization API](https://www.graphhopper.com/blog/2019/05/17/getting-started-with-the-optimization-api-traveling-salesman-problem/).\nIt shows and describes the essential elements to model your vehicle routing problem.\n\nTo explore the full specification, we recommend that you either use our [route editor](https://www.graphhopper.com/blog/2015/07/21/graphhoppers-new-route-optimization-editor/),\nwhich you can find in our [dashboard](https://graphhopper.com/dashboard/),\nor use a REST client such as Insomnia or Postman, as described [here](https://docs.graphhopper.com/#section/Explore-our-APIs/Insomnia).\n\n## Tutorials\n\nWe provide [a number of tutorials](https://www.graphhopper.com/tutorial/) illustrating how to use the Route Optimization API and\nhow to model your vehicle routing problems:\n\n- [Getting Start with the Optimization API - Traveling Salesman Problem](https://www.graphhopper.com/blog/2019/05/17/getting-started-with-the-optimization-api-traveling-salesman-problem/)\n- [How to solve a traveling salesman problem with a week-planning horizon?](https://www.graphhopper.com/blog/2020/07/15/how-to-solve-a-traveling-salesman-problem-with-a-week-planning-horizon-and-driver-shifts/)\n- [How to schedule technicians with skills and multiple dependencies between tasks?](https://www.graphhopper.com/blog/2016/06/03/how-to-route-technicians-with-skills-and-multiple-dependencies-between-tasks/)\n- [What is the difference between the min. of completion time and min. transport time?](https://www.graphhopper.com/blog/2016/06/20/what-is-the-difference-between-the-minimization-of-completion-time-and-minimizing-transport-time/)\n- [How to model multiple delivery routes with a single vehicle?](https://www.graphhopper.com/blog/2016/07/21/how-to-model-multiple-delivery-routes-with-a-single-vehicle/)\n"
},
{
"name": "Routing API",
"description": "\n### Introduction\n\n\n\nThe Routing API is part of the GraphHopper Directions API. Routing is the process of finding the best path connecting\ntwo or more points, where the meaning of ''best'' depends on the vehicle and use case.\n\n### Navigation\nIf you plan to use the Routing API for navigation, have a look at our [open source demo navigation application](https://github.com/graphhopper/graphhopper-navigation-example) and adapt it to your needs.\n\n### Fast\nTo get started using this API, just provide two or more points and retrieve the fastest route through the road\nnetwork that connects them. This type of request is heavily optimized for query performance, so it does not\nallow for some advanced features.\n### Flexible\nUnlock further flexible features via `ch.disable=true`.\n"
},
{
"name": "Matrix API",
"description": "\n### Introduction\n\n\n\nThe Matrix API is part of the [GraphHopper Directions API](https://graphhopper.com/#directions-api) and with\nit you can calculate many-to-many distances and times a lot more efficient than calling the\nRouting API multiple times.\n\nIn the [Routing API](#tag/Routing-API) we support multiple points, so called 'via points', which results in one\nroute being calculated. The Matrix API results in NxM routes, or more precise NxM distances or times being calculated\nbut [is a lot faster](https://www.graphhopper.com/blog/2019/06/04/incredibly-fast-distance-matrix-calculations-with-graphhopper/)\ncompared to NxM single requests.\n\nThe most simple example is a tourist trying to decide\nwhich pizza is close to her instead of using beeline distance she can calculate a 1x4 matrix. Or a delivery service\noften in the need of big NxN matrices to solve vehicle routing problems. For example the [GraphHopper Route Optimization API](#tag/Route-Optimization-API)\nuses the Matrix API under the hood to achieve this.\n\nSome other use cases for the Matrix API:\n\n* Logistic problems often pick up many items from and deliver them to many locations.\n* Calculating detours with many possible points in-between and selecting the best e.g. interesting for ridesharing or taxi applications. For this 1-to-many requests are necessary.\n* Finding the best tour for a tourist in the need to visit as many points of interests as possible.\n* ...\n\n### API Clients and Examples\n\nSee the [clients](#section/API-Clients) section in the main document and [live examples](https://graphhopper.com/api/1/examples/#matrix).\n\n### Description\n\nThe Matrix API calculates the well known distance-matrix for a set of points, i.e. it calculates all the distances\nbetween every point combination. But we do not stop there, we also offer a time-, weight- and route-matrix.\nThe weight-matrix can be used as raw input for e.g. a vehicle routing problem ([VRP](http://en.wikipedia.org/wiki/Vehicle_routing_problem))\nand is more precise than a time- or distance-matrix. E.g. for bike routes the actual weight of a route (e.g. the \"beauty\")\nis what you want to decide if a route is 'better' and not always the taken time or distance.\n\nA simple illustration for a 3x3 matrix with identical from and to points:\n\n- |to_point1|to_point2|to_point3\n:-----------|:--------|:--------|:--------\nfrom_point1 |0 |1->2 | 1->3\nfrom_point2 |2->1 |0 | 2->3\nfrom_point3 |3->1 |3->2 | 0\n\nA simple illustration for a 1x3 matrix with different start- and end-points:\n\n- | to_point1 | to_point2 | t_point3\n:-----------|:-----------|:----------|:--------\nfrom_pointA |A->1 |A->2 |A->3\n\n\nFor every route 1->2, 1-3, ... or A->1,A->2,A->3 you can return only the weight, the time and the distance.\nTo calculate full routes you can use the [Routing API](#tag/Routing-API).\n\n### Limits and Counts\n\nThe cost for one request depends on the number of locations and is documented [here](https://support.graphhopper.com/support/solutions/44000303787#what-is-one-credit).\n\nOne request should not exceed the Matrix API location limit, which depends on the subscription, see the\npricing tab in our dashboard.\n"
},
{
"name": "Geocoding API",
"description": "Everything about geocoding"
},
{
"name": "Isochrone API",
"description": "Everything about isochrones"
},
{
"name": "Map Matching API",
"description": "Everything about map matching aka \"snap to road\""
},
{
"name": "Cluster API",
"description": "\n### Introduction\n\n\n\nIt solves the “capacity clustering problem” by assigning a set of customers to a given number of distinct groups (called clusters).\nThe API “clusters” by minimizing the total distance from each individual customer to its designated group median.\nIt can also consider minimum and maximum capacity restrictions for each group.\n\nClustering can be used in many practical applications.\nFor example, it can help to plan territories, i.e. territory optimization for field teams with large territories for field workers,\nor to solve large vehicle routing problems (VRP).\n"
}
],
"security": [
{
"api_key": []
}
],
"paths": {
"/route": {
"get": {
"summary": "GET Route Endpoint",
"operationId": "getRoute",
"description": "The GET request is the most simple one: just specify the parameter in the URL and you are done.\nCan be tried directly in every browser.\n",
"parameters": [
{
"name": "point",
"in": "query",
"description": "The points for which the route should be calculated. Format: `[latitude,longitude]`. Specify at least an origin and a destination. Via points are possible.\nThe maximum number depends on your plan.\n",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "point_hint",
"in": "query",
"description": "The `point_hint` is typically a road name to which the associated `point` parameter should be snapped to. Specify no `point_hint` parameter or the same number as you have `point` parameters.\n",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "snap_prevention",
"in": "query",
"description": "Optional parameter to avoid snapping to a certain road class or road environment. Currently supported values are `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`. Multiple values are specified like `snap_prevention=ferry&snap_prevention=motorway`.\n",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"in": "query",
"name": "vehicle",
"description": "The vehicle profile for which the route should be calculated.\n",
"schema": {
"$ref": "#/components/schemas/VehicleProfileId"
}
},
{
"in": "query",
"name": "curbside",
"description": "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.\n",
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"any",
"right",
"left"
]
}
}
},
{
"in": "query",
"name": "turn_costs",
"description": "Specifies if turn restrictions should be considered. Enabling this option increases the route computation time. Only supported for motor vehicles and OpenStreetMap.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "locale",
"in": "query",
"description": "The locale of the resulting turn instructions. E.g. `pt_PT` for Portuguese or `de` for German.\n",
"schema": {
"type": "string",
"default": "en"
}
},
{
"name": "elevation",
"in": "query",
"description": "If `true`, a third coordinate, the altitude, is included with all positions in the response.\nThis changes the format of the `points` and `snapped_waypoints` fields of the response, in both their\nencodings. Unless you switch off the `points_encoded` parameter, you need special code on the\nclient side that can handle three-dimensional coordinates.\nA request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "details",
"in": "query",
"description": "Optional parameter to retrieve path details. You can request additional details for the route: `street_name`, \n`time`, `distance`, `max_speed`, `toll`, `road_class`, `road_class_link`, `road_access`, `road_environment`, `lanes`, and `surface`. Read more about the usage of path details [here](https://discuss.graphhopper.com/t/2539).\n",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"in": "query",
"name": "optimize",
"description": "Normally, the calculated route will visit the points in the order you specified them.\nIf you have more than two points, you can set this parameter to `\"true\"` and the points may be re-ordered to minimize the total travel time.\nKeep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.\n",
"schema": {
"type": "string",
"default": "false"
}
},
{
"in": "query",
"name": "instructions",
"description": "If instructions should be calculated and returned\n",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "calc_points",
"in": "query",
"description": "If the points for the route should be calculated at all.\n",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "debug",
"in": "query",
"schema": {
"type": "boolean",
"default": false
},
"description": "If `true`, the output will be formatted.\n"
},
{
"name": "points_encoded",
"in": "query",
"description": "Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact\nbut requires special client code to unpack. (We provide it in our JavaScript client library!)\nSet this parameter to `false` to switch the encoding to simple coordinate pairs like `[lon,lat]`, or `[lon,lat,elevation]`.\nSee the description of the response format for more information.\n",
"schema": {
"type": "boolean",
"default": true
}
},
{
"name": "ch.disable",
"in": "query",
"description": "Use this parameter in combination with one or more parameters from below.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "weighting",
"in": "query",
"description": "Determines the way the \"best\" route is calculated. Besides `fastest` you can use `short_fastest` which finds a reasonable balance between the distance influence (`shortest`) and the time (`fastest`). You could also use `shortest` but is deprecated and not recommended for motor vehicles. All except `fastest` require `ch.disable=true`.\n",
"schema": {
"type": "string",
"default": "fastest"
}
},
{
"name": "heading",
"in": "query",
"description": "Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.\nIn 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.\nThis parameter also influences the tour generated with `algorithm=round_trip` and forces the initial direction. Requires `ch.disable=true`.\n",
"schema": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
},
"explode": true
},
{
"name": "heading_penalty",
"in": "query",
"description": "Time penalty in seconds for not obeying a specified heading. Requires `ch.disable=true`.\n",
"schema": {
"type": "integer",
"format": "int32",
"default": 120
}
},
{
"name": "pass_through",
"in": "query",
"description": "If `true`, u-turns are avoided at via-points with regard to the `heading_penalty`. Requires `ch.disable=true`.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "block_area",
"in": "query",
"description": "Block road access by specifying a point close to the road segment to be blocked, with the format `lat,lon`.\nYou can also block all road segments crossing a geometric shape. Specify a circle using the format `lat,lon,radius`, or a polygon using the format `lat1,lon1,lat2,lon2,...,latN,lonN`.\nYou can specify several shapes, separating them with `;`. Requires `ch.disable=true`.\n",
"schema": {
"type": "string"
}
},
{
"name": "avoid",
"in": "query",
"description": "Specify which road classes and environments you would like to avoid. \nPossible values are `motorway`, `steps`, `track`, `toll`, `ferry`, `tunnel` and `bridge`.\nSeparate several values with `;`. Obviously not all the values make sense for all vehicle profiles e.g. `bike` is already forbidden on a `motorway`. Requires `ch.disable=true`.\n",
"schema": {
"type": "string"
}
},
{
"name": "algorithm",
"in": "query",
"schema": {
"type": "string",
"enum": [
"round_trip",
"alternative_route"
]
},
"description": "Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:\nWith `round_trip`, the route will get you back to where you started. This is meant for fun (think of\na bike trip), so we will add some randomness. And this requires `ch.disable=true`.\nWith `alternative_route`, we give you not one but several routes that are close to optimal, but\nnot too similar to each other. You can control both of these features with additional parameters, see below. \n"
},
{
"name": "round_trip.distance",
"in": "query",
"description": "If `algorithm=round_trip`, this parameter configures approximative length of the resulting round trip. Requires `ch.disable=true`.\n",
"schema": {
"type": "integer",
"format": "int32",
"default": 10000
}
},
{
"name": "round_trip.seed",
"in": "query",
"description": "If `algorithm=round_trip`, this sets the random seed. Change this to get a different tour for each value.\n",
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "alternative_route.max_paths",
"in": "query",
"description": "If `algorithm=alternative_route`, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.\n",
"schema": {
"type": "integer",
"format": "int32",
"default": 2
}
},
{
"name": "alternative_route.max_weight_factor",
"in": "query",
"description": "If `algorithm=alternative_route`, this parameter sets the factor by which the alternatives routes can be longer than the optimal route. Increasing can lead to worse alternatives.\n",
"schema": {
"type": "number",
"default": 1.4
}
},
{
"name": "alternative_route.max_share_factor",
"in": "query",
"description": "If `algorithm=alternative_route`, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.\n",
"schema": {
"type": "number",
"default": 0.6
}
}
],
"tags": [
"Routing API"
],
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&vehicle=car&locale=de&calc_points=false&key=api_key\""
},
{
"lang": "Java",
"source": "OkHttpClient client = new OkHttpClient();\nRequest request = new Request.Builder()\n .url(\"https://graphhopper.com/api/1/route?point=51.131,12.414&point=48.224,3.867&vehicle=car&locale=de&calc_points=false&key=api_key\")\n .get()\n .build();\n\nResponse response = client.newCall(request).execute();"
}
],
"responses": {
"200": {
"description": "Routing Result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RouteResponse"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"400": {
"description": "Your request is not valid. For example, you specified too few or too many points.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"401": {
"description": "Authentication necessary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"429": {
"description": "API limit reached.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"500": {
"description": "Internal server error. We get notified automatically and fix this asap.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"501": {
"description": "Only a special list of vehicles is supported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
}
}
},
"post": {
"summary": "POST Route Endpoint",
"operationId": "postRoute",
"description": "Please see the [GET endpoint](#operation/getRoute) for a simpler method on how to get started.\nIf you are familiar with POST requests and JSON then do not hesitate to continue here.\n\nEspecially when you use many locations you should get familiar with this POST endpoint as the GET endpoint\nhas an URL length limitation. Additionally the request of this POST endpoint can be compressed and can slightly\nspeed up the request.\n\nTo 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.\nThe effected parameters are: `points`, `point_hints` and `snap_preventions`.\n\n**Please note that in opposite to the GET endpoint, points are specified in the order of `longitude, latitude`**.\n\nFor example `point=10,11&point=20,22` will be converted to the `points` array (plural):\n```json\n{ \"points\": [[11,10], [22,20]] }\n```\nNote again that also the order changes from `[latitude,longitude]` to `[longitude,latitude]`\nsimilar to [GeoJson](http://geojson.org/geojson-spec.html#examples).\n\nExample:\n```bash\ncurl -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\"}'\n```\n",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RouteRequest"
}
}
}
},
"tags": [
"Routing API"
],
"responses": {
"200": {
"description": "Routing Result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RouteResponse"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"400": {
"description": "Your request is not valid. For example, you specified too few or too many points.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"401": {
"description": "Authentication necessary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"429": {
"description": "API limit reached.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"500": {
"description": "Internal server error. We get notified automatically and fix this asap.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
},
"501": {
"description": "Only a special list of vehicles is supported.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
},
"headers": {
"X-RateLimit-Limit": {
"description": "Your current daily credit limit.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Your remaining credits until the reset.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "The number of seconds that you have to wait before a reset of the credit count is done.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Credits": {
"description": "The credit costs for this request. Note it could be a decimal and even negative number, e.g. when an async request failed.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/route/info": {
"get": {
"tags": [
"Routing API"
],
"summary": "Coverage information",
"description": "Use this to find out details about the supported vehicle profiles and features, or if you just need to ping the server.\n",
"responses": {
"200": {
"description": "Coverage Information",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InfoResponse"
}
}
}
}
}
}
},
"/isochrone": {
"get": {
"summary": "Isochrone Endpoint",
"operationId": "getIsochrone",
"description": "### Example\nYou can get an example response via:\n\n```\ncurl \"https://graphhopper.com/api/1/isochrone?point=51.131108,12.414551&key=[YOUR_KEY]\"\n```\n\nDon't forget to replace the placeholder with your own key.\n\n### Introduction\n\n\nAn isochrone of a location is ''a line connecting points at which a vehicle arrives at the same time'', see Wikipedia.\nWith the same API you can also calculate isodistances, just use the parameter distance_limit instead of time_limit`.\n\n### Use Cases\nSome possible areas in which this API may be useful to you:\n\n- real estate analysis\n- realtors\n- vehicle scheduling\n- geomarketing\n- reach of electric vehicles\n- transport planning\n- logistics (distribution and retail network planning)\n\n### API Clients and Examples\nSee the [clients](#section/API-Clients) section in the main documentation, and [live examples](https://graphhopper.com/api/1/examples/#isochrone).\n",
"parameters": [
{
"name": "point",
"in": "query",
"description": "Specify the start coordinate",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "time_limit",
"in": "query",
"description": "Specify which time the vehicle should travel. In seconds.",
"schema": {
"default": 600,
"type": "integer",
"format": "int32"
}
},
{
"name": "distance_limit",
"in": "query",
"description": "Specify which distance the vehicle should travel. In meters.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "vehicle",
"in": "query",
"description": "The vehicle profile for which the route should be calculated.\n",
"schema": {
"$ref": "#/components/schemas/VehicleProfileId"
}
},
{
"name": "buckets",
"in": "query",
"description": "Number by which to divide the given `time_limit` to create `buckets` nested isochrones of time intervals `time_limit-n*time_limit/buckets`. Applies analogously to `distance_limit`.",
"schema": {
"default": 1,
"type": "integer",
"format": "int32"
}
},
{
"name": "reverse_flow",
"in": "query",
"description": "If `false` the flow goes from point to the polygon, if `true` the flow goes from the polygon \"inside\" to the point.\nExample use case for `false`: *How many potential customer can be reached within 30min travel time from your store* vs. `true`: *How many customers can reach your store within 30min travel time.*\n",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"name": "weighting",
"in": "query",
"description": "Use `\"shortest\"` to get an isodistance line instead of an isochrone.",
"schema": {
"type": "string",
"enum": [
"fastest",
"shortest"
],
"default": "fastest"
}
}
],
"tags": [
"Isochrone API"
],
"responses": {
"200": {
"description": "Isochrone Result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IsochroneResponse"
}
}
}
},
"default": {
"description": "Unexpected Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GHError"
}
}
}
}
}
}
},
"/matrix": {
"get": {
"summary": "GET Matrix Endpoint",
"operationId": "getMatrix",
"description": "With this Matrix Endpoint you submit the points and parameters via URL parameters and is the most convenient\nas it works out-of-the-box in the browser. If possible you should\nprefer using the [POST Matrix Endpoint](#operation/postMatrix) that avoids problems with many locations\nand automatically gzipps the request (note that all endpoints return gzipped results).\n",
"x-code-samples": [
{
"lang": "Curl",
"source": "curl \"https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747375&point=50.118817,11.983337&type=json&vehicle=car&debug=true&out_array=weights&out_array=times&out_array=distances&key=api_key\""
},
{
"lang": "Java",
"source": "OkHttpClient client = new OkHttpClient();\nRequest request = new Request.Builder()\n .url(\"https://graphhopper.com/api/1/matrix?point=49.932707,11.588051&point=50.241935,10.747375&point=50.118817,11.983337&type=json&vehicle=car&debug=true&out_array=weights&out_array=times&out_array=distances&key=api_key\")\n .get()\n .build();\n\nResponse response = client.newCall(request).execute();"
}
],
"parameters": [
{
"name": "point",
"in": "query",
"description": "Specify multiple points in `latitude,longitude` for which the weight-, route-, time- or distance-matrix should be calculated. In this case the starts are identical to the destinations. If there are N points, then NxN entries will be calculated. The order of the point parameter is important. Specify at least three points. Cannot be used together with from_point or to_point.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "from_point",
"in": "query",
"description": "The starting points for the routes in `latitude,longitude`. E.g. if you want to calculate the three routes A->1, A->2, A->3 then you have one from_point parameter and three to_point parameters.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "to_point",
"in": "query",
"description": "The destination points for the routes in `latitude,longitude`.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "point_hint",
"in": "query",
"description": "Optional parameter. Specifies a hint for each `point` parameter to prefer a certain street for the closest location lookup. E.g. if there is an address or house with two or more neighboring streets you can control for which street the closest location is looked up.",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"explode": true
},
{
"name": "from_point_hint",
"in": "query",
"description": "For the from_point parameter. See point_hint",
"required": false,
"schema": {