DataFire integration for GraphHopper Directions API
npm install @datafire/graphhopperClient library for GraphHopper Directions API
bash
npm install --save @datafire/graphhopper
`
`js
let graphhopper = require('@datafire/graphhopper').create({
api_key: ""
});.then(data => {
console.log(data);
});
`Description
With the GraphHopper Directions API you can integrate A-to-B route planning, turn-by-turn navigation,
route optimization, isochrone calculations and other tools in your application.
The GraphHopper Directions API consists of the following RESTful web services:
* Routing API,
* Route Optimization API,
* Isochrone API,
* Map Matching API,
* Matrix API,
* Geocoding API and
* Cluster API.
Explore our APIs
Get started
1. Sign up for GraphHopper
2. Create an API key
Each API part has its own documentation. Jump to the desired API part and learn about the API through the given examples and tutorials.
In 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.
Insomnia
To explore our APIs with Insomnia, follow these steps:
1. Open Insomnia and Import our workspace.
2. Specify your API key in your workspace: Manage Environments -> Base Environment ->
"api_key": your API key
3. Start exploringPostman
To explore our APIs with Postman, follow these steps:
1. Import our request collections as well as our environment file.
2. Specify your API key in your environment:
"api_key": your API key
3. Start exploringAPI Client Libraries
To speed up development and make coding easier, we offer the following client libraries:
* JavaScript client - try the live examples
* Others like C#, Ruby, PHP, Python, ... automatically created for the Route Optimization API
$3
If you create your own client, make sure it supports http/2 and gzipped responses for best speed.
If you use the Matrix or Route Optimization API and want to solve large problems, we recommend you to reduce bandwidth
by compressing your POST request
and specifying the header as follows:
Content-Encoding: gzip.Contact Us
If you have problems or questions, please read the following information:
- FAQ
- Public forum
- Contact us
To stay informed about the latest developments, you can
- follow us on twitter,
- read our blog,
- watch our documentation,
- sign up for our newsletter or
- our forum.
Select the channel you like the most.
Map Data and Routing Profiles
Currently, our main data source is OpenStreetMap. We also integrated other network data providers.
This chapter gives an overview about the options you have.
OpenStreetMap
#### Geographical Coverage
OpenStreetMap covers the whole world. If you want to see for yourself if we can provide data suitable for your region,
please visit GraphHopper Maps.
You can edit and modify OpenStreetMap data if you find that important information is missing, e.g. a weight limit for a bridge.
Here is a beginner's guide that shows how to add data. If you have edited data, we usually consider your data after 1 week at the latest.
#### Supported Vehicle Profiles
The Routing, Matrix and Route Optimization APIs support the following vehicle profiles:
Name | Description | Restrictions | Icon
-----------|:----------------------|:--------------------------|:---------------------------------------------------------
car | Car mode | car access | !car image
small_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 | !small truck image
truck | 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 | !truck image
scooter | Moped mode | Fast inner city, often used for food delivery, is able to ignore certain bollards, maximum speed of roughly 50km/h | !scooter image
foot | Pedestrian or walking without dangerous SAC-scales | foot access | !foot image
hike | Pedestrian or walking with priority for more beautiful hiking tours and potentially a bit longer than
foot. Walking duration is influenced by elevation differences. | foot access | !hike image
bike | Trekking bike avoiding hills | bike access | !bike image
mtb | Mountainbike | bike access | !Mountainbike image
racingbike| Bike preferring roads | bike access | !racingbike imagePlease note:
* all motor vehicles (
car, small_truck, truck and scooter) support turn restrictions via turn_costs=true
* the free package supports only the vehicle profiles car, bike or foot
* 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.
* 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.
* a sophisticated motorcycle profile is available up on request. It is powered by the Kurviger Routing API and favors curves and slopes while avoiding cities and highways.
TomTom
If you want to include traffic, you can purchase the TomTom Add-on.
This Add-on only uses TomTom's road network and historical traffic information.
Live traffic is not yet considered. If you are interested to learn how we consider traffic information, we recommend that you read this article.
Please note the following:
* Currently we only offer this for our Route Optimization API.
* In addition to our terms, you need to accept TomTom's End User License Aggreement.
We do not* use TomTom's web services. We only use their data with our software.
Contact us for more details.
#### Geographical Coverage
We offer
- Europe including Russia
- North, Central and South America
- Saudi Arabia
- United Arab Emirates
- South Africa
- Australia
#### Supported Vehicle Profiles
Name | Description | Restrictions | Icon
-----------|:----------------------|:--------------------------|:---------------------------------------------------------
car | Car mode | car access | !car image
small_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 | !small truck image
Actions
$3
The Cluster endpoint is used with a POST request towards
https://graphhopper.com/api/1/cluster?key=. The solution will be provided in the JSON response.
Please note that for problems that take longer than 10 seconds a bad request error is returned.
In this case please use the asynchronous Batch Cluster Endpoint instead.`js
graphhopper.solveClusteringProblem({
"body": {}
}, context)
`#### Input
* input
object
* body required ClusterRequest#### Output
* output ClusterResponse
$3
Prefer the synchronous endpoint and use this Batch Cluster endpoint for
long running problems only. The work flow is asynchronous:
- send a POST request towards
https://graphhopper.com/api/1/cluster/calculate?key= and fetch the job_id.
- poll the solution every 500ms until it gives status=finished. Do this with a GET request
towards https://graphhopper.com/api/1/cluster/solution/.`js
graphhopper.asyncClusteringProblem({
"body": {}
}, context)
`#### Input
* input
object
* body required ClusterRequest#### Output
* output JobId
$3
This endpoint returns the solution of the clustering problems submitted to the Batch Cluster endpoint.
You can fetch it with the job_id, you have been sent.`js
graphhopper.getClusterSolution({
"jobId": ""
}, context)
`#### Input
* input
object
* jobId required string: Request solution with jobId#### Output
* output ClusterResponse
$3
$3
_Geocoding_ describes the process of transforming an textual address representation to a coordinate (
latitude,longitude).
For example the conversion from Berlin to 52.5170365,13.3888599._Reverse geocoding_ converts a coordinate to a textual address representation or place name. Find out more about Geocoding itself on Wikipedia.
`js
graphhopper.getGeocode({}, context)
`#### Input
* input
object
* q string: If you do forward geocoding, this is required and is a textual description of the address you are looking for.
* locale string: 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.
* limit integer: Specify the maximum number of results to return
* reverse boolean: 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.
* debug boolean: If true, the output will be formatted.
* point string: _Forward geocoding_: The location bias in the format 'latitude,longitude' e.g. point=45.93272,11.58803. _Reverse geocoding_: The location to find amenities, cities.
* provider string: The provider parameter is currently under development and can fall back to default at any time.#### Output
* output GeocodingResponse
$3
$3
You can get an example response via:`
curl "https://graphhopper.com/api/1/isochrone?point=51.131108,12.414551&key=[YOUR_KEY]"
`Don't forget to replace the placeholder with your own key.
$3
!Isochrone screenshotAn isochrone of a location is ''a line connecting points at which a vehicle arrives at the same time'', see Wikipedia.
With the same API you can also calculate isodistances, just use the parameter distance_limit instead of time_limit
.- real estate analysis
- realtors
- vehicle scheduling
- geomarketing
- reach of electric vehicles
- transport planning
- logistics (distribution and retail network planning)
``js`
graphhopper.getIsochrone({
"point": ""
}, context)
#### Input
* input objectstring
* point required : Specify the start coordinateinteger
* time_limit : Specify which time the vehicle should travel. In seconds.integer
* distance_limit : Specify which distance the vehicle should travel. In meters.string
* vehicle (values: car, bike, foot, hike, mtb, racingbike, scooter, truck, small_truck): The vehicle profile for which the route should be calculated.integer
buckets : Number by which to divide the given time_limit to create buckets nested isochrones of time intervals time_limit-ntime_limit/buckets. Applies analogously to distance_limit.boolean
* reverse_flow : If false the flow goes from point to the polygon, if true the flow goes from the polygon "inside" to the point.string
* weighting (values: fastest, shortest): Use "shortest" to get an isodistance line instead of an isochrone.
#### Output
* output IsochroneResponse
``
curl -XPOST -H "Content-Type: application/gpx+xml" "https://graphhopper.com/api/1/match?vehicle=car&key=[YOUR_KEY]" --data @/path/to/some.gpx
A minimal working GPX file looks like
`gpx`
The Map Matching API is part of the GraphHopper Directions API and with this API you can snap measured GPS points typically as GPX files to a digital
road network to e.g. clean data or attach certain data like elevation or turn instructions to it. Read more at Wikipedia.
In the example screenshot above and demo you see the Map Matching API in action where the black line is the GPS track and the green one is matched result.
Most of the times, you can simply POST a GPX file, but some of the request parameters of the Routing API apply here, too.
One request should not exceed the Map Matching API location limit depending on the package, see the pricing in our dashboard.
`js`
graphhopper.postGPX({}, context)
#### Input
* input objectinteger
* gps_accuracy : Specify the precision of a point, in meterstring
* vehicle : Specify the vehicle profile like car
#### Output
* output RouteResponse
`js`
graphhopper.getMatrix({}, context)
#### Input
* input objectarray
* point : 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.array
* from_point : 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.array
* to_point : The destination points for the routes in latitude,longitude.array
* point_hint : 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.array
* from_point_hint : For the from_point parameter. See point_hintarray
* to_point_hint : For the to_point parameter. See point_hintarray
* snap_prevention : 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=motorwayarray
* curbside : 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.array
* from_curbside : Curbside setting for the from_point parameter. See curbside.array
* to_curbside : Curbside setting for the to_point parameter. See curbside.array
* out_array : 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.string
* vehicle (values: car, bike, foot, hike, mtb, racingbike, scooter, truck, small_truck): The vehicle profile for which the matrix should be calculated.boolean
* fail_fast : 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).boolean
* turn_costs : Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
#### Output
* output MatrixResponse
The GET endpoint has an URL length limitation, which hurts for many locations per request.
In those cases use this POST endpoint with a JSON as input. The only parameter in the URL will be the key.
Both request scenarios are identical except that all singular parameter names are named as their plural for a POST request.
The effected parameters are: points, from_points, to_points, and out_arrays. For the remaining parameters
please refer to the guide of the GET endpoint.
Please note that in contrast to GET endpoint the points have to be specified as longitude, latitude pairs (in that order, similar to GeoJson).
For example the query point=10,11&point=20,22&vehicle=car will be converted to the following JSON:`json`
{ "points": [[11,10], [22,20]], "vehicle": "car" }
A complete curl Example:
`bash`
curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix?key=[YOUR_KEY]" -d '{"elevation":false,"out_arrays":["weights", "times"],"from_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"to_points":[[-0.087891,51.534377],[-0.090637,51.467697],[-0.171833,51.521241],[-0.211487,51.473685]],"vehicle":"car"}'
`js`
graphhopper.postMatrix({}, context)
#### Input
* input object
#### Output
* output MatrixResponse
The Batch Matrix endpoint allows using matrices with more locations and works asynchronously - similar to the Batch Route Optimization endpoint:
* Create a HTTP POST request against /matrix/calculate and add the key in the URL: /matrix/calculate?key=[YOUR_KEY]. This will give you the job_id from the response json like { "job_id": "7ac65787-fb99-4e02-a832-2c3010c70097" }/matrix/solution/[job_id]
* Poll via HTTP GET requests every 500ms against
Here are some full examples via curl:
`bash`
$ curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/matrix/calculate?key=[YOUR_KEY]" -d '{"points":[[13.29895,52.48696],[13.370876,52.489575],[13.439026,52.511206]]}'
{"job_id":"7ac65787-fb99-4e02-a832-2c3010c70097"}
Pick the returned job_id and use it in the next GET requests:`bash`
$ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
{"status":"waiting"}
When the calculation is finished (status:finished) the JSON response will contain the full matrix JSON under solution:`bash`
$ curl -X GET "https://graphhopper.com/api/1/matrix/solution/7ac65787-fb99-4e02-a832-2c3010c70097?key=[YOUR_KEY]"
{"solution":{"weights":[[0.0,470.453,945.414],[503.793,0.0,580.871],[970.49,569.511,0.0]],"info":{"copyrights":["GraphHopper","OpenStreetMap contributors"]}},"status":"finished"}
Please note that if an error occured while calculation the JSON will not have a status but contain directly the error message e.g.:
`json`
{"message":"Cannot find from_points: 1","hints":[{...}]}
`js`
graphhopper.calculateMatrix({}, context)
#### Input
* input object
#### Output
* output JobId
`js`
graphhopper.getMatrixSolution({
"jobId": ""
}, context)
#### Input
* input objectstring
* jobId required : Request solution with jobId
#### Output
* output MatrixResponse
`js`
graphhopper.getRoute({
"point": []
}, context)
#### Input
* input objectarray
* point required : The points for which the route should be calculated. Format: [latitude,longitude]. Specify at least an origin and a destination. Via points are possible.array
* point_hint : 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.array
* snap_prevention : 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.string
* vehicle (values: car, bike, foot, hike, mtb, racingbike, scooter, truck, small_truck): The vehicle profile for which the route should be calculated.array
* curbside : 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.boolean
* turn_costs : Specifies if turn restrictions should be considered. Enabling this option increases the route computation time. Only supported for motor vehicles and OpenStreetMap.string
* locale : The locale of the resulting turn instructions. E.g. pt_PT for Portuguese or de for German.boolean
* elevation : If true, a third coordinate, the altitude, is included with all positions in the response.array
* details : Optional parameter to retrieve path details. You can request additional details for the route: street_name, string
* optimize : Normally, the calculated route will visit the points in the order you specified them.boolean
* instructions : If instructions should be calculated and returnedboolean
* calc_points : If the points for the route should be calculated at all.boolean
* debug : If true, the output will be formatted.boolean
* points_encoded : Allows changing the encoding of location data in the response. The default is polyline encoding, which is compactboolean
* ch.disable : Use this parameter in combination with one or more parameters from below.string
* weighting : 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.array
* heading : Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.integer
* heading_penalty : Time penalty in seconds for not obeying a specified heading. Requires ch.disable=true.boolean
* pass_through : If true, u-turns are avoided at via-points with regard to the heading_penalty. Requires ch.disable=true.string
* block_area : Block road access by specifying a point close to the road segment to be blocked, with the format lat,lon.string
* avoid : Specify which road classes and environments you would like to avoid. string
* algorithm (values: round_trip, alternative_route): Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:integer
* round_trip.distance : If algorithm=round_trip, this parameter configures approximative length of the resulting round trip. Requires ch.disable=true.integer
* round_trip.seed : If algorithm=round_trip, this sets the random seed. Change this to get a different tour for each value.integer
* alternative_route.max_paths : If algorithm=alternative_route, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.number
* alternative_route.max_weight_factor : 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.number
* alternative_route.max_share_factor : If algorithm=alternative_route, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.
#### Output
* output RouteResponse
Especially when you use many locations you should get familiar with this POST endpoint as the GET endpoint
has an URL length limitation. Additionally the request of this POST endpoint can be compressed and can slightly
speed up the request.
To do a request you send JSON data. Both request scenarios GET and POST are identical except that all singular parameter names are named as their plural for a POST request.
The effected parameters are: points, point_hints and snap_preventions.
Please note that in opposite to the GET endpoint, points are specified in the order of longitude, latitude.
For example point=10,11&point=20,22 will be converted to the points array (plural):`json`
{ "points": [[11,10], [22,20]] }[latitude,longitude]
Note again that also the order changes from to [longitude,latitude]
similar to GeoJson.
Example:
`bash`
curl -X POST -H "Content-Type: application/json" "https://graphhopper.com/api/1/route?key=[YOUR_KEY]" -d '{"elevation":false,"points":[[-0.087891,51.534377],[-0.090637,51.467697]],"vehicle":"car"}'
`js`
graphhopper.postRoute({}, context)
#### Input
* input object
* body RouteRequest
#### Output
* output RouteResponse
`js`
graphhopper.route.info.get(null, context)
#### Input
This action has no parameters
#### Output
* output InfoResponse
To get started with the Route Optimization API, please read the introduction.
To solve a new vehicle routing problem, make a HTTP POST to this URL
``
https://graphhopper.com/api/1/vrp?key=
It returns the solution to this problem in the JSON response.
Please note that this URL is very well suited to solve minor problems.
Larger vehicle routing problems, which take longer than 10 seconds to solve, cannot be solved.
To solve them, please use the batch mode URL instead.
`js`
graphhopper.solveVRP({
"body": {}
}, context)
#### Input
* input object
* body required Request
#### Output
* output Response
To solve a vehicle routing problem, perform the following steps:
1.) Make a HTTP POST to this URL
``
https://graphhopper.com/api/1/vrp/optimize?key=
It returns a job id (job_id).
2.) Take the job id and fetch the solution for the vehicle routing problem from this URL:
``
https://graphhopper.com/api/1/vrp/solution/
We recommend to query the solution every 500ms until it returns 'status=finished'.
Note: Since the workflow is a bit more cumbersome and since you lose some time in fetching the solution, you should always prefer
the synchronous endpoint. You should use the batch mode only for long running problems.
`js`
graphhopper.asyncVRP({
"body": {}
}, context)
#### Input
* input object
* body required Request
#### Output
* output JobId
Take the job id and fetch the solution for the vehicle routing problem from this URL:
``
https://graphhopper.com/api/1/vrp/solution/
You get the job id by sending a vehicle routing problem to the batch mode URL.
`js`
graphhopper.getSolution({
"jobId": ""
}, context)
#### Input
* input objectstring
* jobId required : Request solution with jobId
#### Output
* output Response
* address ResponseAddress
* arr_date_time string: Arrival date time with offset like this 1970-01-01T01:00+01:00. If you do not use time-dependent optimization, this is null.
* arr_time integer: Arrival time at this activity in seconds. If type is start, this is not available (since it makes no sense to have arr_time at start). However, end_time is available and actually means \"departure time\" at start location. It is important to note that arr_time does not necessarily mean \"start of underlying activity\", it solely means arrival time at activity location. If this activity has no time windows and if there are no further preparation times, arr_time is equal to activity start time.
* distance integer: cumulated distance from start to this activity in m
* driving_time integer: cumulated driving time from start to this driver activity in seconds
* end_date_time string: End date time with offset like this 1970-01-01T01:00+01:00. If you do not use time-dependent optimization, this is null.
* end_time integer: End time of and thus departure time at this activity. If type is end, this is not available (since it makes no sense to have an end_time at end) end_time at each activity is equal to the departure time at the activity location.
* id string: Id referring to the underlying service or shipment, i.e. the shipment or service this activity belongs to
* load_after array: Array with size/capacity dimensions after this activity
* items integer: dimension value
* load_before array: Array with size/capacity dimensions before this activity
* items integer: dimension value
* location_id string: Id that refers to address
* preparation_time integer: preparation time at this activity in seconds
* type string (values: start, end, service, pickupShipment, deliverShipment, pickup, delivery, break): type of activity
* waiting_time integer: Waiting time at this activity in seconds. A waiting time can occur if the activity has at least one time window. If arr_time < time_window.earliest a waiting time of time_window_earliest - arr_time occurs.$3
* Address object
* curbside string (values: right, left, any): Optional parameter. Specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. Only supported for motor vehicles and OpenStreetMap.
* lat required number: Latitude of location.
* location_id required string: Specifies the id of the location.
* lon required number: Longitude of location.
* name string: Name of location.
* street_hint string: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. 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.$3
* Algorithm object: Use objectives instead.
* objective string (values: transport_time, completion_time)
* problem_type string (values: min, min-max)$3
* BadRequest object
* hints array: More detailed information about the error.
* items ErrorMessage
* message string: Short error message
* status string: status$3
* Cluster object
* ids array: Array of customer ids assigned to this specific cluster
* items string
* quantity number: Cluster size$3
* ClusterConfiguration object
* clustering ClusterConfigurationClustering
* response_type string: Specifies the response format. You can either choose geojson or json.
* routing ClusterConfigurationRouting$3
* ClusterConfigurationClustering object
* max_quantity number: Specifies max. quantity in a cluster
* min_quantity number: Specifies min. quantity in a cluster
* num_clusters number: Specifies the number of clusters$3
* ClusterConfigurationRouting object
* cost_per_meter number: Cost per meter (travel distance)
* cost_per_second number: Cost per second (travel time)
* profile string: The routing profile for which the travel times and distances should be calculated. Other profiles are listed here$3
* ClusterCustomer object
* address ClusterCustomerAddress
* id string: id of customer
* quantity number: demand of customer$3
* ClusterCustomerAddress object
* lat number: Latitude
* lon number: Longitude
* street_hint string: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. 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.$3
* ClusterRequest object
* configuration ClusterConfiguration
* customers array
* items ClusterCustomer$3
* ClusterResponse object
* clusters array
* items Cluster
* copyrights array
* items string
* processing_time number
* status string (values: waiting_in_queue, processing, finished): Indicates the current status of the job
* waiting_time_in_queue number$3
* Configuration object: Specifies general configurations that are taken into account when solving the vehicle routing problem.
* routing Routing$3
* CostMatrix object
* data object: JSON data of matrix response
* info object: Additional information for your request
* copyrights array
* items string
* took number
* distances array
* items array
* items number
* times array
* items array
* items integer
* location_ids array
* items string
* profile string: vehicle profile or empty if catch all fallback
* type string (values: default, google): type of cost matrix, currently default or google are supported$3
* Detail object
* code integer: Reason code
* id string: Id of unassigned service/shipment
* reason string: Human readable reason as listed above$3
* DriveTimeBreak object
* duration required integer: Specifies the duration of the break in seconds.
* initial_driving_time integer: Specifies the initial (current) driving time of a driver to allow dynamic adaptations in seconds.
* max_driving_time required integer: Specifies the max driving time (in a row) without break in seconds.
* possible_split array: Array specifying how a break duration (in seconds) can be split into several smaller breaks
* items integer$3
* EncodedLineString string: A polyline-encoded list of positions. You'll need to decode this string in client code. We provide open source code in Java and JavaScript.$3
* ErrorMessage object
* details string: Details
* message string: error message$3
* GHError object
* hints array
* items object
* message string
* message string$3
* GeocodingLocation object
* city string: The city of the address
* country string: The country of the address
* housenumber string: The housenumber of the address
* name string: The name of the entity. Can be a boundary, POI, address, etc
* osm_id string: The OSM ID of the entity
* osm_key string: The OSM key of the entity
* osm_type string: N = node, R = relation, W = way
* point GeocodingPoint
* postcode string: The postcode of the address
* state string: The state of the address
* street string: The street of the address$3
* GeocodingPoint object
* lat number: Latitude
* lng number: Longitude$3
* GeocodingResponse object
* hits array
* items GeocodingLocation
* took number: in ms$3
* GroupRelation object
* groups required array: An array of groups that should be related
* items string: group of services or shipments
* type required string: Specifies the type of relation. It must be either of type in_sequence or in_direct_sequence.$3
* InfoResponse object: Information about the server and the geographical area that it covers.
* bbox string: The bounding box of the geographical area covered by this GraphHopper instance. Format: "minLon,minLat,maxLon,maxLat"object: The supported features, such as elevation, per vehicle profile.string: The version of the GraphHopper server that provided this response. This is not related to the API version.objectintegerstring: Detailsobjectarraystringarray: The list of polygons in GeoJson format. It can be used e.g. in the Leaflet framework:object: A found pathobjectintegerstringobjectstring: UUID. Unique id for your job/request with which you can fetch your solutionobjectarray: Specifies an array of shipment and/or service ids that are in relation. If you deal with services then you need to use the id of your services in ids. To also consider sequences of the pickups and deliveries of your shipments, you need to use a special ID, i.e. use your shipment id plus the keyword _pickup or _delivery. If you want to place a service or shipment activity at the beginning of your route, use the special ID start. In turn, use end to place it at the end of the route.stringstring: Specifies the type of relation. It must be either of type in_same_route, in_sequence or in_direct_sequence.string: Id of pre-assigned vehicle, i.e. the vehicle id that is determined to conduct the services and shipments in this relation.objectarray: A list of coordinate pairs or triples, [lon,lat] or [lon,lat,elevation].arraynumberstringobjectboolean: 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).array: See curbsidesof symmetrical matrixstringarray: See point_hintsof symmetrical matrixstringarray: The starting points for the routes in an array of [longitude,latitude]. For instance, if you want to calculate three routes from point A such as A->1, A->2, A->3 then you have one from_point parameter and three to_point parameters.arraynumberarray: Specifies which matrices should be included in the response. Specify one or more of the following options weights, times, 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.stringarray: See snap_preventions of symmetrical matrixstringarray: See curbsidesof symmetrical matrixstringarray: See point_hintsof symmetrical matrixstringarray: The destination points for the routes in an array of [longitude,latitude].arraynumberboolean: Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.objectarray: The distance matrix for the specified points in the same order as the time matrix. The distances are in meters. If fail_fast=false the matrix will contain null for connections that could not be found.arraynumberarray: Optional. Additional response dataobjectstring: Details of this hintarray: Optional. An array of from_point indices of points that could not be found. Will only be added if fail_fast=false and some from_points were not found.
* items number
* invalid_to_points array: Optional. An array of to_point indices of points that could not be found. Will only be added if fail_fast=false and some to_points were not found.numberstring: Short description of this hintarray: Optional. An array of two-element arrays representing the from/to_point indices of points for which no connection could be found. Will only be added if fail_fast=false and some connections were not found.arraynumberarray: The time matrix for the specified points in the order [[from1->to1, from1->to2, ...], [from2->to1, from2->to2, ...], ...]. The times are in seconds. If fail_fast=false the matrix will contain null for connections that could not be found.arraynumberarray: The weight matrix for the specified points in the same order as the time matrix. The weights for different vehicles can have a different unit but the weights array is perfectly suited as input for Vehicle Routing Problems as it is currently faster to calculate. If fail_fast=false the matrix will contain null for connections that could not be found.arraynumberobjectstring (values: min, min-max): Type of objective function, i.e. min or min-max.string (values: completion_time, transport_time, vehicles, activities): The value of the objective function.objectarrayarrayarraynumberstringobjectarray: Specifies your own tranport time and distance matrices.array: Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized.array: Defines additional relationships between orders.array: Specifies the orders of the type "service". These are, for example, pick-ups, deliveries or other stops that are to be approached by the specified vehicles. Each of these orders contains only one location.array: Specifies the available shipments. Each shipment contains a pickup and a delivery stop, which must be processed one after the other.array: Specifies the available vehicle types. These types can be assigned to vehicles.array: Specifies the available vehicles.objectarraystring: Attributioninteger: Processing time in ms. If job is still waiting in queue, processing_time is 0string (values: waiting_in_queue, processing, finished): Indicates the current status of the jobinteger: Waiting time in msobject: Address of activitynumber: Latitude of location.string: Specifies the id of the location.number: Longitude of location.string: Name of location.string: Optional parameter. Specifies a hint for each address to better snap the coordinates (lon,lat) to road network. 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.object: Additional information for your requestarray: Attribution according to our documentation is necessary if no white-label option included.stringnumberobjectarray: Array of activitiesinteger: Completion time of route in secondsinteger: Distance of route in meterarray: Array of route planning pointsinteger: Preparation time of route in secondsinteger: Service duration of route in secondsinteger: Transport time of route in secondsstring: Id of vehicle that operates routeinteger: Waiting time of route in secondsobjectarrayobjectstringobjectstring (values: round_trip, alternative_route): Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:integer: If algorithm=alternative_route, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.number: If algorithm=alternative_route, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.number: 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.string: Specify which road classes and environments you would like to avoid.string: Block road access via a point with the format latitude,longitudeboolean: If the points for the route should be calculated at all.boolean: Use this parameter in combination with one or more parameters from below.array: 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.string (values: any, right, left)boolean: If true, the output will be formatted.array: Optional parameter to retrieve path details. You can request additional details for the route: street_name,stringboolean: If true, a third coordinate, the altitude, is included with all positions in the response.integer: Time penalty in seconds for not obeying a specified heading. Requires ch.disable=true.array: Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.integerboolean: If instructions should be calculated and returnedstring: The locale of the resulting turn instructions. E.g. pt_PT for Portuguese or de for German.string: Normally, the calculated route will visit the points in the order you specified them.boolean: If true, u-turns are avoided at via-points with regard to the heading_penalty. Requires ch.disable=true.array: Optional parameter. Specifies a hint for each point in the points array 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.stringarray: The points for the route in an array of [longitude,latitude]. For instance, if you want to calculate a route from point A to B to Carraynumberboolean: Allows changing the encoding of location data in the response. The default is polyline encoding, which is compactinteger: If algorithm=round_trip, this parameter configures approximative length of the resulting round trip. Requires ch.disable=true.integer: If algorithm=round_trip, this sets the random seed. Change this to get a different tour for each value.array: Optional parameter to avoid snapping to a certain road class or road environment. Current supported values motorway, trunk, ferry, tunnel, bridge and fordstringstring: Determines the way the ''best'' route is calculated. Default is fastest. Other options are shortest (e.g. for vehicle=foot or bike) and short_fastest which finds a reasonable balance between shortest and fastest. Requires ch.disable=true.objectarrayobjectnumber: The total ascent, in meters.array: The bounding box of the route geometry. Format: [minLon, minLat, maxLon, maxLat].numbernumber: The total descent, in meters.object: Details, as requested with the details parameter. Consider the value {"street_name": [[0,2,"Frankfurter Straße"],[2,6,"Zollweg"]]}.number: The total distance, in meters. To get this information for one 'leg' please read this blog post.array: The instructions for this route. This feature is under active development, and our instructions can sometimes be misleading,objectnumber: The distance for this instruction, in meters.integer: Only available for USE_ROUNDABOUT instructions. The count of exits at which the route leaves the roundabout.array: Two indices into points, referring to the beginning and the end of the segment of the routeintegerinteger: A number which specifies the sign to show:string: The name of the street to turn onto in order to follow the route.string: A description what the user has to do in order to follow the route. The language depends on the locale parameter.integer: The duration for this instruction, in milliseconds.number: Only available for USE_ROUNDABOUT instructions. The radian of the route within the roundabout 0 < r < 2PI for clockwise andboolean: Whether the points and snapped_waypoints fields are polyline-encoded strings rather than JSON arraysarray: An array of indices (zero-based), specifiying the order in which the input points are visited.integerinteger: The total travel time, in milliseconds. To get this information for one 'leg' please read this blog post.object: This contains all routing specific configurations.boolean: It lets you specify whether the API should provide you with route geometries for vehicle routes or not. Thus, you do not need to do extra routing to get the polyline for each route.boolean: indicates whether historical traffic information should be consideredstring (values: ignore, soft, strict): In some cases curbside constraints cannot be fulfilled. For example in one-way streets you cannot arrive at a building that is on the left side of the street such that the building is to the right of you (unless you drove the one-way street the wrong/illegal way). You can set the curbside_strictness to soft to ignore the curbside constraint in such cases or set it to strict to get an error response instead. You can also set it to ignore to ignore all curbside constraints (this is useful to compare the results with and without constraints without modifying every single address).boolean: indicates whether matrix calculation should fail fast when points cannot be connectedstring (values: openstreetmap, tomtom): specifies the data provider, read more about it here.boolean: Indicates whether a solution includes snapped waypoints. In contrary to the address coordinate a snapped waypoint is the access point to the (road) network.array: Prevents snapping locations to road links of specified road types, e.g. to motorway.string (values: motorway, trunk, bridge, ford, tunnel, ferry)objectarray: Specifies an array of allowed vehicles, i.e. array of vehicle ids. For example, if this service can only be conducted EITHER by technician_peter OR technician_stefan specify this as follows: ["technician_peter","technician_stefan"].stringarray: Specifies an array of disallowed vehicles, i.e. array of vehicle ids.stringinteger: Specifies the duration of the service in seconds, i.e. how long it takes at the customer site.string: Group this service belongs to. See the group relation and this post on how to utilize this.string: Specifies the id of the service. Ids need to be unique so there must not be two services/shipments with the same id.integer: Specifies the maximum time in seconds a delivery can stay in the vehicle. Currently, it only works with services of "type":"delivery".string: Meaningful name for service, e.g. "deliver pizza".integer: Specifies the preparation time in seconds. It can be used to model parking lot search time since if you have 3 identical locations in a row, it only falls due once.integer: Specifies the priority. Can be 1 = high priority to 10 = low priority. Often there are more services/shipments than the available vehicle fleet can handle. Then you can set priorities to differentiate high priority tasks from those that could be left unassigned. I.e. the lower the priority the earlier these tasks are omitted in the solution.array: Specifies an array of required skills, i.e. array of string (not case sensitive). For example, if this service needs to be conducted by a technician having a drilling_machine and a screw_driver then specify the array as follows: ["drilling_machine","screw_driver"]. This means that the service can only be done by a vehicle (technician) that has the skills drilling_machine AND screw_driver in its skill array. Otherwise it remains unassigned.stringarray: Size can have multiple dimensions and should be in line with the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimension, volume and weight, then specify it as follow [ 20, 5 ] assuming a volume of 20 and a weight of 5.integerarray: Specifies an array of time window objects (see time_window object below). Specify the time either with the recommended Unix time stamp (the number of seconds since 1970-01-01) or you can also count the seconds relative to Monday morning 00:00 and define the whole week in seconds. For example, Monday 9am is then represented by 9hour 3600sec/hour = 32400. In turn, Wednesday 1pm corresponds to 2day 24hour/day 3600sec/hour + 1day 13hour/day 3600sec/hour = 219600. See this tutorial for more information.string (values: service, pickup, delivery): Specifies type of service. This makes a difference if items are loaded or unloaded, i.e. if one of the size dimensions > 0. If it is specified as service or pickup, items are loaded and will stay in the vehicle for the rest of the route (and thus consumes capacity for the rest of the route). If it is a delivery, items are implicitly loaded at the beginning of the route and will stay in the route until delivery (and thus releases capacity for the rest of the route).objectarray: Specifies an array of allowed vehicles, i.e. array of vehicle ids. For example, if this shipment can only be conducted EITHER by "technician_peter" OR "technician_stefan" specify this as follows: ["technician_peter","technician_stefan"].stringarray: Specifies an array of disallowed vehicles, i.e. array of vehicle ids.stringstring: Specifies the id of the shipment. Ids need to be unique so there must not be two services/shipments with the same id.integer: Specifies the maximum time in seconds a shipment can stay in the vehicle.string: Meaningful name for shipment, e.g. "pickup and deliver pizza to Peter".integer: Specifies the priority. Can be 1 = high priority to 10 = low priority. Often there are more services/shipments than the available vehicle fleet can handle. Then you can set priorities to differentiate high priority tasks from those that could be left unassigned. I.e. the lower the priority the earlier these tasks are omitted in the solution.array: Specifies an array of required skills, i.e. array of string (not case sensitive). For example, if this shipment needs to be conducted by a technician having a drilling_machine and a screw_driver then specify the array as follows: ["drilling_machine","screw_driver"]. This means that the service can only be done by a vehicle (technician) that has the skills drilling_machine AND screw_driver in its skill array. Otherwise it remains unassigned.stringarray: Size can have multiple dimensions and should be in line with the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimension, volume and weight, then specify it as follow [ 20, 5 ] assuming a volume of 20 and a weight of 5.integerobject: Access point to the (road)network. It is only available if return_snapped_waypoints is true (be default it is false).number: Latitude of location.number: Longitude of location.object: Only available if status field indicates finished.integer: Overall completion time in seconds, i.e. the sum of each routes/drivers operation time.integerinteger: Overall distance travelled in meter, i.e. the sum of each route's transport distanceinteger: Operation time of longest route in seconds.integer: Number of jobs that could not be assigned to final solution.integer: Number of employed vehicles.integer: Overall preparation time in seconds.