openapi-directory
Version:
Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS
1 lines • 169 kB
JSON
{"openapi":"3.0.0","servers":[{"url":"https://graphhopper.com/api/1"}],"info":{"contact":{"email":"support@graphhopper.com","name":"API Support","url":"https://www.graphhopper.com/"},"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, the Route Optimization API or the Cluster 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`. This will also avoid the HTTP 413 error \"Request Entity Too Large\".\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- [GraphHopper Status Page](https://status.graphhopper.com/)\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 repository](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","termsOfService":"https://www.graphhopper.com/terms/","title":"GraphHopper Directions API","version":"1.0.0","x-apisguru-categories":["location"],"x-logo":{"altText":"GraphHopper","url":"https://twitter.com/graphhopper/profile_image?size=original"},"x-origin":[{"format":"openapi","url":"https://docs.graphhopper.com/openapi.json","version":"3.0"}],"x-providerName":"graphhopper.com"},"security":[{"api_key":[]}],"tags":[{"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":"Route Optimization 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":"Routing 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":"Matrix API"},{"description":"Everything about geocoding","name":"Geocoding API"},{"description":"Everything about isochrones","name":"Isochrone API"},{"description":"Everything about map matching aka \"snap to road\"","name":"Map Matching 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","name":"Cluster API"}],"paths":{"/cluster":{"post":{"description":"\nThe Cluster endpoint is used with a POST request towards\n`https://graphhopper.com/api/1/cluster?key=<your_key>`. The solution will be provided in the JSON response.\nPlease note that for problems that take longer than 10 seconds a bad request error is returned.\nIn this case please use the asynchronous [Batch Cluster Endpoint](#operation/asyncClusteringProblem) instead.\n","operationId":"solveClusteringProblem","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterRequest"}}},"description":"Request object that contains the problem to be solved","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterResponse"}}},"description":"A response containing the solution","headers":{"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"}},"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"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}},"description":"Error occurred when reading the request. Request is invalid."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorMessage"}}},"description":"Error occurred on server side."}},"summary":"POST Cluster Endpoint","tags":["Cluster API"]}},"/cluster/calculate":{"post":{"description":"\nPrefer the [synchronous endpoint](#operation/solveClusteringProblem) and use this Batch Cluster endpoint for\nlong running problems only. The work flow is asynchronous:\n\n- send a POST request towards `https://graphhopper.com/api/1/cluster/calculate?key=<your_key>` and fetch the job_id.\n- poll the solution every 500ms until it gives `status=finished`. Do this with a GET request\n towards `https://graphhopper.com/api/1/cluster/solution/<job_id>?key=<your_key>`.\n","operationId":"asyncClusteringProblem","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterRequest"}}},"description":"Request object that contains the problem to be solved","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}},"description":"A jobId you can use to retrieve your solution from the server - see solution endpoint.","headers":{"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"}},"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"}}},"links":{"GetSolutionByJobId":{"description":"The `job_id` value returned in the response can be used as the `jobId` parameter in `GET /vrp/{jobId}`.\n","operationId":"getSolution","parameters":{"jobId":"$response.body#/job_id"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}},"description":"Error occurred when reading client request. Request is invalid."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalErrorMessage"}}},"description":"Error occurred on server side."}},"summary":"Batch Cluster Endpoint","tags":["Cluster API"]}},"/cluster/solution/{jobId}":{"get":{"description":"This endpoint returns the solution of the clustering problems submitted to the [Batch Cluster endpoint](#operation/asyncClusteringProblem).\nYou can fetch it with the job_id, you have been sent.\n","operationId":"getClusterSolution","parameters":[{"description":"Request solution with jobId","in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterResponse"}}},"description":"A response containing the solution","headers":{"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"}},"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"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}},"description":"Error occurred on client side such as invalid input."},"404":{"content":{"application/json":{"schema":{"properties":{"message":{"description":"Error message","example":"Invalid job_id 73314c89-ee4b-459c-aca4-0ad6d6e558da","type":"string"},"status":{"default":"finished","description":"status","example":"finished","type":"string"}},"type":"object"}}},"description":"Requested solution could not be found."},"500":{"description":"Error occurred on server side."}},"summary":"GET Batch Solution Endpoint","tags":["Cluster API"]}},"/geocode":{"get":{"description":"\n### Introduction\n\n\n\n_Geocoding_ describes the process of transforming an textual address representation to a coordinate (`latitude,longitude`).\nFor example the conversion from `Berlin` to `52.5170365,13.3888599`.\n\n_Reverse geocoding_ converts a coordinate to a textual address representation or place name. Find out more about Geocoding itself on [Wikipedia](http://en.wikipedia.org/wiki/Geocoding).\n","operationId":"getGeocode","parameters":[{"description":"If you do forward geocoding, this is `required` and is a textual description of the address you are looking for.","in":"query","name":"q","schema":{"type":"string"}},{"description":"Display the search results for the specified locale. Currently French (fr), English (en), German (de) and Italian (it) are supported. If the locale wasn't found the default (en) is used.","in":"query","name":"locale","schema":{"default":"en","type":"string"}},{"description":"Specify the maximum number of results to return","in":"query","name":"limit","schema":{"default":10,"format":"int32","type":"integer"}},{"description":"It is `required` to be `true` if you want to do a reverse geocoding request. If it is `true`, `point` must be defined as well, and `q` must not be used.","in":"query","name":"reverse","schema":{"default":false,"type":"boolean"}},{"description":"If `true`, the output will be formatted.","in":"query","name":"debug","schema":{"default":false,"type":"boolean"}},{"description":"_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.","in":"query","name":"point","schema":{"type":"string"}},{"description":"The provider parameter is currently under development and can fall back to `default` at any time.\nThe intend is to provide alternatives to our default geocoder. Each provider has its own strenghts and might fit better for certain scenarios, so it's worth to compare the different providers.\nTo try it append the `provider`parameter to the URL like `&provider=nominatim`,\nthe result structure should be identical in all cases - if not, please report this back to us.\nKeep in mind that some providers do not support certain parameters or don't return some fields, for example `osm_id` and `osm_type` are not supported by every geocoding provider.\nIf you would like to use additional parameters of one of the providers, but it's not available for the GraphHopper Geocoding API, yet? Please contact us.\n\nThe credit costs can be different for all providers - see [here](https://support.graphhopper.com/support/solutions/articles/44000718211-what-is-one-credit-) for more information about it.\n\nCurrently, only the default provider and gisgraphy supports autocompletion of partial search strings.\n\nAll providers support normal \"forward\" geocoding and reverse geocoding via `reverse=true`.\n\n#### Default (`provider=default`)\n\nThis provider returns results of our internal geocoding engine, as described above.\nIn addition to the above documented parameters the following parameters are possible:\n* `bbox` - the expected format is `minLon,minLat,maxLon,maxLat`\n* `osm_tag` - you can filter `key:value` or exclude places with certain OpenStreetMap tags `!key:value`. E.g. `osm_tag=tourism:museum` or just the key `osm_tag=tourism`. To exclude multiple tags you add multiple `osm_tag` parameters.\n\n#### Nominatim (`provider=nominatim`)\n\nThe GraphHopper Directions API uses a commercially hosted Nominatim geocoder. You can try this provider [here](https://nominatim.openstreetmap.org/). The provider does **not** fall under the [restrictions](https://operations.osmfoundation.org/policies/nominatim/) of the Nominatim instance hosted by OpenStreetMap.\n\nIn addition to the above documented parameters Nominatim allows to use the following parameters, which can be used as documented [here](https://github.com/openstreetmap/Nominatim/blob/master/docs/api/Search.md#parameters):\n\n* `viewbox` - the expected format is `minLon,minLat,maxLon,maxLat`\n* `bounded` - If 1 and a viewbox is given, restrict the result to items contained within that viewbox. Default is 0.\n\n#### Gisgraphy (`provider=gisgraphy`)\n\nThis provider returns results from the Gisgraphy geocoder which you can try [here](https://services.gisgraphy.com/static/leaflet/index.html).\n\n**Limitations:** The `locale` parameter is not supported. Gisgraphy does not return OSM tags or an extent.\n\nGisgraphy has a special autocomplete API, which you can use by adding `autocomplete=true` (does not work with `reverse=true`). The autocomplete API is optimized on predicting text input, but returns less information.\n\nIn addition to the above documented parameters Gisgraphy allows to use the following parameters, which can be used as documented [here](https://www.gisgraphy.com/documentation/user-guide.php#geocodingservice):\n\n* `radius` - radius in meters\n* `country` - restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country.\n\n#### NetToolKit (`provider=nettoolkit`)\n\nThis provider returns results from the NetToolKit provider which is specialized for US addresses and provides a wrapper around Nominatim for other addresses. You can try it [here](https://www.nettoolkit.com/geo/demo).\n\nThe following additional NetToolKit parameters are supported (read [here](https://www.nettoolkit.com/docs/geo/geocoding) for more details):\n- `source`: User can choose which source provider to geocode the address, this value is \"NetToolKit\" by default\n- `country_code`: an iso-3166-2 country code (e.g : US) filter the results to the specify country code\n\n**Limitations:** NetToolKit does not support the `locale` parameter. NetToolKit does not return OSM tags (e.g. osm_id, osm_type, osm_value).\n\n#### OpenCage Data (`provider=opencagedata`)\n\nThis provider returns results from the OpenCageData geocoder which you can try [here](https://geocoder.opencagedata.com/demo).\n\nIn addition to the above documented parameters OpenCage Data allows to use the following parameters, which can be used as documented [here](https://geocoder.opencagedata.com/api#forward-opt):\n\n* countrycode - The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States. \n* bounds - the expected format is `minLon,minLat,maxLon,maxLat`\n","in":"query","name":"provider","schema":{"default":"default","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodingResponse"}}},"description":"An array found locations","headers":{"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"}},"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"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected error"}},"summary":"Geocoding Endpoint","tags":["Geocoding API"],"x-code-samples":[{"lang":"Curl","source":"curl \"https://graphhopper.com/api/1/geocode?q=berlin&locale=de&debug=true&key=api_key\""},{"lang":"Java","source":"OkHttpClient client = new OkHttpClient();\nRequest request = new Request.Builder()\n .url(\"https://graphhopper.com/api/1/geocode?q=berlin&locale=de&debug=true&key=api_key\")\n .get()\n .build();\n\nResponse response = client.newCall(request).execute();"}]}},"/isochrone":{"get":{"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","operationId":"getIsochrone","parameters":[{"description":"Specify the start coordinate","in":"query","name":"point","required":true,"schema":{"type":"string"}},{"description":"Specify which time the vehicle should travel. In seconds.","in":"query","name":"time_limit","schema":{"default":600,"format":"int32","type":"integer"}},{"description":"Specify which distance the vehicle should travel. In meters.","in":"query","name":"distance_limit","schema":{"format":"int32","type":"integer"}},{"description":"The vehicle profile for which the route should be calculated.\n","in":"query","name":"vehicle","schema":{"$ref":"#/components/schemas/VehicleProfileId"}},{"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`.","in":"query","name":"buckets","schema":{"default":1,"format":"int32","type":"integer"}},{"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","in":"query","name":"reverse_flow","schema":{"default":false,"type":"boolean"}},{"description":"Use `\"shortest\"` to get an isodistance line instead of an isochrone.","in":"query","name":"weighting","schema":{"default":"fastest","enum":["fastest","shortest"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsochroneResponse"}}},"description":"Isochrone Result"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected Error"}},"summary":"Isochrone Endpoint","tags":["Isochrone API"]}},"/match":{"post":{"description":"### Example\nYou get an example response for a GPX via:\n\n```\ncurl -XPOST -H \"Content-Type: application/gpx+xml\" \"https://graphhopper.com/api/1/match?vehicle=car&key=[YOUR_KEY]\" --data @/path/to/some.gpx\n```\n\nA minimal working GPX file looks like\n```gpx\n<gpx>\n <trk>\n <trkseg>\n <trkpt lat=\"51.343657\" lon=\"12.360708\"></trkpt>\n <trkpt lat=\"51.343796\" lon=\"12.361337\"></trkpt>\n <trkpt lat=\"51.342784\" lon=\"12.361882\"></trkpt>\n </trkseg>\n </trk>\n</gpx>\n```\n\n### Introduction\n\n\nThe 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\nroad network to e.g. clean data or attach certain data like elevation or turn instructions to it. Read more at Wikipedia.\n\nIn 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.\n\nMost of the times, you can simply POST a GPX file, but some of the request parameters of the [Routing API](#tag/Routing-API) apply here, too.\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/#map-matching).\n\n### Limits and Counts\nThe cost for one request depends on the number of GPS location and is documented [here](https://graphhopper.com/api/1/docs/FAQ/).\n\nOne request should not exceed the Map Matching API location limit depending on the package, see the pricing in our dashboard.\n","operationId":"postGPX","parameters":[{"description":"Specify the precision of a point, in meter","in":"query","name":"gps_accuracy","required":false,"schema":{"type":"integer"}},{"description":"Specify the vehicle profile like car","in":"query","name":"vehicle","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteResponse"}}},"description":"Routing Result","headers":{"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"}},"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"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected Error"}},"summary":"Map-match a GPX file","tags":["Map Matching API"]}},"/matrix":{"get":{"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 can also gzip the **request**. (Note, that all endpoints return gzipped responses).\n","operationId":"getMatrix","parameters":[{"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.","explode":true,"in":"query","name":"point","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"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.","explode":true,"in":"query","name":"from_point","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"The destination points for the routes in `latitude,longitude`.","explode":true,"in":"query","name":"to_point","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"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.","explode":true,"in":"query","name":"point_hint","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"For the from_point parameter. See point_hint","explode":true,"in":"query","name":"from_point_hint","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"For the to_point parameter. See point_hint","explode":true,"in":"query","name":"to_point_hint","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"Optional parameter to avoid snapping to a certain road class or road environment. Current supported values `motorway`, `trunk`, `ferry`, `tunnel`, `bridge` and `ford`. Multiple values are specified like `snap_prevention=ferry&snap_prevention=motorway`\n","explode":true,"in":"query","name":"snap_prevention","schema":{"items":{"type":"string"},"type":"array"}},{"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.","explode":true,"in":"query","name":"curbside","required":false,"schema":{"items":{"enum":["any","right","left"],"type":"string"},"type":"array"}},{"description":"Curbside setting for the from_point parameter. See curbside.","explode":true,"in":"query","name":"from_curbside","required":false,"schema":{"items":{"enum":["any","right","left"],"type":"string"},"type":"array"}},{"description":"Curbside setting for the to_point parameter. See curbside.","explode":true,"in":"query","name":"to_curbside","required":false,"schema":{"items":{"enum":["any","right","left"],"type":"string"},"type":"array"}},{"description":"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.","explode":true,"in":"query","name":"out_array","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"The vehicle profile for which the matrix should be calculated.","in":"query","name":"vehicle","schema":{"$ref":"#/components/schemas/VehicleProfileId"}},{"description":"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 `false` the time/weight/distance matrix will be calculated for all valid points and contain the `null` value for all entries that could not be calculated. The `hint` field of the response will also contain additional information about what went wrong (see its documentation).","in":"query","name":"fail_fast","required":false,"schema":{"default":true,"type":"boolean"}},{"description":"Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.","in":"query","name":"turn_costs","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixResponse"}}},"description":"Matrix API response","headers":{"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"}},"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"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected Error"}},"summary":"GET Matrix Endpoint","tags":["Matrix API"],"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();"}]},"post":{"description":"\nThe [GET endpoint](#operation/getMatrix) has an URL length limitation, which hurts for many locations per request.\nIn those cases use this POST endpoint with a JSON as input. The only parameter in the URL will be the key.\nBoth request scenarios are identical except that all singular parameter names are named as their plural for a POST request.\nThe effected parameters are: `points`, `from_points`, `to_points`, and `out_arrays`. For the remaining parameters\nplease refer to the [guide of the GET endpoint](#operation/getMatrix).\n\n**Please note that in contrast to GET endpoint the points have to be specified as `[longitude, latitude]` array (in that order, similar to [GeoJson](http://geojson.org/geojson-spec.html#examples))**.\n\nFor example the query `point=10,11&point=20,22&vehicle=car` will be converted to the following JSON:\n```json\n{ \"points\": [[11,10], [22,20]], \"vehicle\": \"car\" }\n```\n\nA complete curl Example:\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \"https://graphhopper.com/api/1/matrix?key=[YOUR_KEY]\" -d '{\"elevation\":false,\"out_arrays\":[\"weights\", \"times\"],\"from_points\":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],\"to_points\":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],\"vehicle\":\"car\"}'\n```\n","operationId":"postMatrix","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MatrixRequest"},{"$ref":"#/components/schemas/SymmetricalMatrixRequest"}]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixResponse"}}},"description":"Matrix API response","headers":{"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"}},"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"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected Error"}},"summary":"POST Matrix Endpoint","tags":["Matrix API"]}},"/matrix/calculate":{"post":{"description":"Prefer the [synchronous endpoint](#operation/postMatrix) and use this Batch endpoint for long running problems only.\n\nThe Batch Matrix endpoint allows using matrices with more locations and works asynchronously - similar to the [Batch Route Optimization endpoint](#operation/asyncVRP):\n * Create a HTTP POST request against `/matrix/calculate` and add the key in the URL: `/matrix/calculate?key=[YOUR_KEY]`. This will give you the `job_id` from the response json like `{ \"job_id\": \"7ac65787-fb99-4e02-a832-2c3010c70097\" }`\n * Poll via HTTP GET requests every 500ms against `/matrix/solution/[job_id]`\n\nHere are some full examples via curl:\n```bash\n$ 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]]}'\n{\"job_id\":\"7ac65787-fb99-4e02-a832-2c3010c70097\"}\n```\n\nPick the returned `job_id` and use it in the next GET requests:\n```bash\n$ curl -X GET \"https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]\"\n{\"status\":\"waiting\"}\n```\n\nWhen the calculation is finished (`status:finished`) the JSON response will contain the full matrix JSON under `solution`:\n```bash\n$ curl -X GET \"https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]\"\n{\"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\"}\n```\n\nPlease note that if an error occured while calculation the JSON will not have a status but contain directly the error message e.g.:\n```json\n{\"message\":\"Cannot find from_points: 1\"}\n```\nAnd the optional `hints` array.\n","operationId":"calculateMatrix","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MatrixRequest"},{"$ref":"#/components/schemas/SymmetricalMatrixRequest"}]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobId"}}},"description":"A jobId you can use to retrieve your solution from the server.","headers":{"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"}},"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"}}}},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GHError"}}},"description":"Unexpected Error"}},"summary":"Batch Matrix Endpoint","tags":["Matrix API"]}},"/matrix/solution/{jobId}":{"get":{"description":"This endpoint returns the solution of a JSON submitted to the Batch Matrix endpoint. You can fetch it with the job_id, you have been sent.\n","operationId":"getMatrixSolution","parameters":[{"description":"Request solution with jobId","in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatrixResponse"}}},"description":"