graphhopper.directions
Module graphhopper.directions
API
Definitions
![](https://bcentral-packageicons.azureedge.net/images/ballerinax_graphhopper.directions_1.5.1.png)
ballerinax/graphhopper.directions Ballerina library
Overview
This is a generated connector for GraphHopper Directions API v1.0.0 OpenAPI Specification.
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](#tag/Routing-API), * [Route Optimization API](#tag/Route-Optimization-API), * [Isochrone API](#tag/Isochrone-API), * [Map Matching API](#tag/Map-Matching-API), * [Matrix API](#tag/Matrix-API), * [Geocoding API](#tag/Geocoding-API) and * [Cluster API](#tag/Cluster-API).
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create a GraphHopper Account
- Obtaining tokens
- Obtain your token by following this link
- Learn more on GraphHopper
Clients![](/images/permalink.svg)
graphhopper.directions: Client![](/images/permalink.svg)
This is a generated connector for GraphHopper Directions API v1.0.0 OpenAPI Specification.
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.
Constructor![](/images/permalink.svg)
Gets invoked to initialize the connector
.
The connector initialization requires setting the API credentials.
Create an GraphHopper account and obtain tokens following this guide.
init (ApiKeysConfig apiKeyConfig, ConnectionConfig config, string serviceUrl)
- apiKeyConfig ApiKeysConfig - API keys for authorization
- config ConnectionConfig {} - The configurations to be used when initializing the
connector
- serviceUrl string "https://graphhopper.com/api/1" - URL of the target service
getRoute![](/images/permalink.svg)
function getRoute(string[] point, string[]? pointHint, string[]? snapPrevention, VehicleProfileId? vehicle, string[]? curbside, boolean turnCosts, string locale, boolean elevation, string[]? details, string optimize, boolean instructions, boolean calcPoints, boolean debug, boolean pointsEncoded, boolean chDisable, string weighting, int[]? heading, int headingPenalty, boolean passThrough, string? blockArea, string? avoid, string? algorithm, int roundTripDistance, int? roundTripSeed, int alternativeRouteMaxPaths, decimal alternativeRouteMaxWeightFactor, decimal alternativeRouteMaxShareFactor) returns RouteResponse|error
GET Route Endpoint
Parameters
- point string[] - The points for which the route should be calculated. Format:
[latitude,longitude]
. Specify at least an origin and a destination. Via points are possible. The maximum number depends on your plan.
- pointHint string[]? (default ()) - The
point_hint
is typically a road name to which the associatedpoint
parameter should be snapped to. Specify nopoint_hint
parameter or the same number as you havepoint
parameters.
- snapPrevention string[]? (default ()) - Optional parameter to avoid snapping to a certain road class or road environment. Currently supported values are
motorway
,trunk
,ferry
,tunnel
,bridge
andford
. Multiple values are specified likesnap_prevention=ferry&snap_prevention=motorway
.
- vehicle VehicleProfileId? (default ()) - The vehicle profile for which the route should be calculated.
- curbside string[]? (default ()) - 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.
- turnCosts boolean (default false) - Specifies if turn restrictions should be considered. Enabling this option increases the route computation time. Only supported for motor vehicles and OpenStreetMap.
- locale string (default "en") - The locale of the resulting turn instructions. E.g.
pt_PT
for Portuguese orde
for German.
- elevation boolean (default false) - If
true
, a third coordinate, the altitude, is included with all positions in the response. This changes the format of thepoints
andsnapped_waypoints
fields of the response, in both their encodings. Unless you switch off thepoints_encoded
parameter, you need special code on the client side that can handle three-dimensional coordinates. A request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.
- details string[]? (default ()) - Optional parameter to retrieve path details. You can request additional details for the route:
street_name
,time
,distance
,max_speed
,toll
,road_class
,road_class_link
,road_access
,road_environment
,lanes
, andsurface
. Read more about the usage of path details here.
- optimize string (default "false") - Normally, the calculated route will visit the points in the order you specified them. If you have more than two points, you can set this parameter to
"true"
and the points may be re-ordered to minimize the total travel time. Keep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.
- instructions boolean (default true) - If instructions should be calculated and returned
- calcPoints boolean (default true) - If the points for the route should be calculated at all.
- debug boolean (default false) - If
true
, the output will be formatted.
- pointsEncoded boolean (default true) - Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact but requires special client code to unpack. (We provide it in our JavaScript client library!) Set this parameter to
false
to switch the encoding to simple coordinate pairs like[lon,lat]
, or[lon,lat,elevation]
. See the description of the response format for more information.
- chDisable boolean (default false) - Use this parameter in combination with one or more parameters from below.
- weighting string (default "fastest") - Determines the way the "best" route is calculated. Besides
fastest
you can useshort_fastest
which finds a reasonable balance between the distance influence (shortest
) and the time (fastest
). You could also useshortest
but is deprecated and not recommended for motor vehicles. All exceptfastest
requirech.disable=true
.
- heading int[]? (default ()) - Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points. In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree. This parameter also influences the tour generated with
algorithm=round_trip
and forces the initial direction. Requiresch.disable=true
.
- headingPenalty int (default 120) - Time penalty in seconds for not obeying a specified heading. Requires
ch.disable=true
.
- passThrough boolean (default false) - If
true
, u-turns are avoided at via-points with regard to theheading_penalty
. Requiresch.disable=true
.
- blockArea string? (default ()) - Block road access by specifying a point close to the road segment to be blocked, with the format
lat,lon
. You can also block all road segments crossing a geometric shape. Specify a circle using the formatlat,lon,radius
, or a polygon using the formatlat1,lon1,lat2,lon2,...,latN,lonN
. You can specify several shapes, separating them with;
. Requiresch.disable=true
.
- avoid string? (default ()) - Specify which road classes and environments you would like to avoid. Possible values are
motorway
,steps
,track
,toll
,ferry
,tunnel
andbridge
. Separate several values with;
. Obviously not all the values make sense for all vehicle profiles e.g.bike
is already forbidden on amotorway
. Requiresch.disable=true
.
- algorithm string? (default ()) - Rather than looking for the shortest or fastest path, this parameter lets you solve two different problems related to routing: With
alternative_route
, we give you not one but several routes that are close to optimal, but not too similar to each other. Withround_trip
, the route will get you back to where you started. This is meant for fun (think of a bike trip), so we will add some randomness. Theround_trip
option requiresch.disable=true
. You can control both of these features with additional parameters, see below.
- roundTripDistance int (default 10000) - If
algorithm=round_trip
, this parameter configures approximative length of the resulting round trip. Requiresch.disable=true
.
- roundTripSeed int? (default ()) - If
algorithm=round_trip
, this sets the random seed. Change this to get a different tour for each value.
- alternativeRouteMaxPaths int (default 2) - If
algorithm=alternative_route
, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.
- alternativeRouteMaxWeightFactor decimal (default 1.4) - 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.
- alternativeRouteMaxShareFactor decimal (default 0.6) - If
algorithm=alternative_route
, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.
Return Type
- RouteResponse|error - Routing Result
postRoute![](/images/permalink.svg)
function postRoute(RouteRequest payload) returns RouteResponse|error
POST Route Endpoint
Parameters
- payload RouteRequest - Route request details
Return Type
- RouteResponse|error - Routing Result
getCoverageInformation![](/images/permalink.svg)
function getCoverageInformation() returns InfoResponse|error
Coverage information
Return Type
- InfoResponse|error - Coverage Information
getIsochrone![](/images/permalink.svg)
function getIsochrone(string point, int timeLimit, int? distanceLimit, VehicleProfileId? vehicle, int buckets, boolean reverseFlow, string weighting) returns IsochroneResponse|error
Isochrone Endpoint
Parameters
- point string - Specify the start coordinate
- timeLimit int (default 600) - Specify which time the vehicle should travel. In seconds.
- distanceLimit int? (default ()) - Specify which distance the vehicle should travel. In meters.
- vehicle VehicleProfileId? (default ()) - The vehicle profile for which the route should be calculated.
- buckets int (default 1) - Number by which to divide the given
time_limit
to createbuckets
nested isochrones of time intervalstime_limit-n*time_limit/buckets
. Applies analogously todistance_limit
.
- reverseFlow boolean (default false) - If
false
the flow goes from point to the polygon, iftrue
the flow goes from the polygon "inside" to the point. Example use case forfalse
: 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.
- weighting string (default "fastest") - Use
"shortest"
to get an isodistance line instead of an isochrone.
Return Type
- IsochroneResponse|error - Isochrone Result
getMatrix![](/images/permalink.svg)
function getMatrix(string[]? point, string[]? fromPoint, string[]? toPoint, string[]? pointHint, string[]? fromPointHint, string[]? toPointHint, string[]? snapPrevention, string[]? curbside, string[]? fromCurbside, string[]? toCurbside, string[]? outArray, VehicleProfileId? vehicle, boolean failFast, boolean turnCosts) returns MatrixResponse|error
GET Matrix Endpoint
Parameters
- point string[]? (default ()) - 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.
- fromPoint string[]? (default ()) - 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.
- toPoint string[]? (default ()) - The destination points for the routes in
latitude,longitude
.
- pointHint string[]? (default ()) - 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.
- fromPointHint string[]? (default ()) - For the from_point parameter. See point_hint
- toPointHint string[]? (default ()) - For the to_point parameter. See point_hint
- snapPrevention string[]? (default ()) - Optional parameter to avoid snapping to a certain road class or road environment. Current supported values
motorway
,trunk
,ferry
,tunnel
,bridge
andford
. Multiple values are specified likesnap_prevention=ferry&snap_prevention=motorway
- curbside string[]? (default ()) - 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.
- fromCurbside string[]? (default ()) - Curbside setting for the from_point parameter. See curbside.
- toCurbside string[]? (default ()) - Curbside setting for the to_point parameter. See curbside.
- outArray string[]? (default ()) - 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.
- vehicle VehicleProfileId? (default ()) - The vehicle profile for which the matrix should be calculated.
- failFast boolean (default true) - Specifies whether or not the matrix calculation should return with an error as soon as possible in case some points cannot be found or some points are not connected. If set to
false
the time/weight/distance matrix will be calculated for all valid points and contain thenull
value for all entries that could not be calculated. Thehint
field of the response will also contain additional information about what went wrong (see its documentation).
- turnCosts boolean (default false) - Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
Return Type
- MatrixResponse|error - Matrix API response
postMatrix![](/images/permalink.svg)
function postMatrix(MatrixBody payload) returns MatrixResponse|error
POST Matrix Endpoint
Parameters
- payload MatrixBody - Matrix Request Detail
Return Type
- MatrixResponse|error - Matrix API response
calculateMatrix![](/images/permalink.svg)
function calculateMatrix(MatrixCalculateBody payload) returns JobId|error
Batch Matrix Endpoint
Parameters
- payload MatrixCalculateBody - Matrix request details
getMatrixSolution![](/images/permalink.svg)
function getMatrixSolution(string jobId) returns MatrixResponse|error
GET Batch Matrix Endpoint
Parameters
- jobId string - Request solution with jobId
Return Type
- MatrixResponse|error - A response containing the matrix
postGPX![](/images/permalink.svg)
function postGPX(int? gpsAccuracy, string? vehicle) returns RouteResponse|error
Map-match a GPX file
Parameters
- gpsAccuracy int? (default ()) - Specify the precision of a point, in meter
- vehicle string? (default ()) - Specify the vehicle profile like car
Return Type
- RouteResponse|error - Routing Result
getGeocode![](/images/permalink.svg)
function getGeocode(string? q, string locale, int 'limit, boolean reverse, boolean debug, string? point, string provider) returns GeocodingResponse|error
Geocoding Endpoint
Parameters
- q string? (default ()) - If you do forward geocoding, this is
required
and is a textual description of the address you are looking for.
- locale string (default "en") - 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 int (default 10) - Specify the maximum number of results to return
- reverse boolean (default false) - It is
required
to betrue
if you want to do a reverse geocoding request. If it istrue
,point
must be defined as well, andq
must not be used.
- debug boolean (default false) - If
true
, the output will be formatted.
- point string? (default ()) - Forward geocoding: The location bias in the format 'latitude,longitude' e.g. point=45.93272,11.58803. Reverse geocoding: The location to find amenities, cities.
- provider string (default "default") - The provider parameter is currently under development and can fall back to
default
at any time. The 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. To try it append theprovider
parameter to the URL like&provider=nominatim
, the result structure should be identical in all cases - if not, please report this back to us. Keep in mind that some providers do not support certain parameters or don't return some fields, for exampleosm_id
andosm_type
are not supported by every geocoding provider. If 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. The credit costs can be different for all providers - see here for more information about it. Currently, only the default provider and gisgraphy supports autocompletion of partial search strings. All providers support normal "forward" geocoding and reverse geocoding viareverse=true
. #### Default (provider=default
) This provider returns results of our internal geocoding engine, as described above. In addition to the above documented parameters the following parameters are possible: *bbox
- the expected format isminLon,minLat,maxLon,maxLat
*osm_tag
- you can filterkey:value
or exclude places with certain OpenStreetMap tags!key:value
. E.g.osm_tag=tourism:museum
or just the keyosm_tag=tourism
. To exclude multiple tags you add multipleosm_tag
parameters. #### Nominatim (provider=nominatim
) The GraphHopper Directions API uses a commercially hosted Nominatim geocoder. You can try this provider here. The provider does not fall under the restrictions of the Nominatim instance hosted by OpenStreetMap. In addition to the above documented parameters Nominatim allows to use the following parameters, which can be used as documented here: *viewbox
- the expected format isminLon,minLat,maxLon,maxLat
*bounded
- If 1 and a viewbox is given, restrict the result to items contained within that viewbox. Default is 0. #### Gisgraphy (provider=gisgraphy
) This provider returns results from the Gisgraphy geocoder which you can try here. Limitations: Thelocale
parameter is not supported. Gisgraphy does not return OSM tags or an extent. Gisgraphy has a special autocomplete API, which you can use by addingautocomplete=true
(does not work withreverse=true
). The autocomplete API is optimized on predicting text input, but returns less information. In addition to the above documented parameters Gisgraphy allows to use the following parameters, which can be used as documented here: *radius
- radius in meters *country
- restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country. #### NetToolKit (provider=nettoolkit
) This 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. The following additional NetToolKit parameters are supported (read here for more details): -source
: User can choose which source provider to geocode the address, this value is "NetToolKit" by default -country_code
: an iso-3166-2 country code (e.g : US) filter the results to the specify country code Limitations: NetToolKit does not support thelocale
parameter. NetToolKit does not return OSM tags (e.g. osm_id, osm_type, osm_value). #### OpenCage Data (provider=opencagedata
) This provider returns results from the OpenCageData geocoder which you can try here. In addition to the above documented parameters OpenCage Data allows to use the following parameters, which can be used as documented here: * 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. * bounds - the expected format isminLon,minLat,maxLon,maxLat
Return Type
- GeocodingResponse|error - An array found locations
solveVRP![](/images/permalink.svg)
POST route optimization problem
Parameters
- payload Request - The request that contains the vehicle routing problem to be solved.
asyncVRP![](/images/permalink.svg)
POST route optimization problem (batch mode)
Parameters
- payload Request - The request that contains the problem to be solved.
Return Type
getSolution![](/images/permalink.svg)
GET the solution (batch mode)
Parameters
- jobId string - Request solution with jobId
solveClusteringProblem![](/images/permalink.svg)
function solveClusteringProblem(ClusterRequest payload) returns ClusterResponse|error
POST Cluster Endpoint
Parameters
- payload ClusterRequest - Request object that contains the problem to be solved
Return Type
- ClusterResponse|error - A response containing the solution
asyncClusteringProblem![](/images/permalink.svg)
function asyncClusteringProblem(ClusterRequest payload) returns JobId|error
Batch Cluster Endpoint
Parameters
- payload ClusterRequest - Request object that contains the problem to be solved
Return Type
getClusterSolution![](/images/permalink.svg)
function getClusterSolution(string jobId) returns ClusterResponse|error
GET Batch Solution Endpoint
Parameters
- jobId string - Request solution with jobId
Return Type
- ClusterResponse|error - A response containing the solution
Records![](/images/permalink.svg)
graphhopper.directions: Activity![](/images/permalink.svg)
Fields
- 'type string? - type of activity
- id string? - Id referring to the underlying service or shipment, i.e. the shipment or service this activity belongs to
- location_id string? - Id that refers to address
- address ResponseAddress? - Address of activity
- arr_time int? - Arrival time at this activity in seconds. If type is
start
, this is not available (since it makes no sense to havearr_time
at start). However,end_time
is available and actually means "departure time" at start location. It is important to note thatarr_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.
- end_time int? - 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 anend_time
at end)end_time
at each activity is equal to the departure time at the activity location.
- 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
.
- 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
.
- waiting_time int? - 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 oftime_window_earliest
-arr_time
occurs.
- preparation_time int? - preparation time at this activity in seconds
- distance int? - cumulated distance from start to this activity in m
- driving_time int? - cumulated driving time from start to this driver activity in seconds
- load_before int[]? - Array with size/capacity dimensions before this activity
- load_after int[]? - Array with size/capacity dimensions after this activity
graphhopper.directions: Address![](/images/permalink.svg)
Fields
- location_id string - Specifies the id of the location.
- name string? - Name of location.
- lon float - Longitude of location.
- lat float - Latitude 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.
- curbside string? - 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.
graphhopper.directions: Algorithm![](/images/permalink.svg)
Use objectives
instead.
Deprecated
Fields
- problem_type string? - Problem type
- objective string? - Objective type
graphhopper.directions: ApiKeysConfig![](/images/permalink.svg)
Provides API key configurations needed when communicating with a remote HTTP endpoint.
Fields
- key string - Represents API Key
key
graphhopper.directions: BadRequest![](/images/permalink.svg)
Fields
- message string? - Short error message
- hints ErrorMessage[]? - Optional error information.
- status string? - status
graphhopper.directions: ClientHttp1Settings![](/images/permalink.svg)
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy ProxyConfig? - Proxy server related options
graphhopper.directions: Cluster![](/images/permalink.svg)
Fields
- quantity int? - Cluster size
- ids string[]? - Array of customer ids assigned to this specific cluster
graphhopper.directions: ClusterConfiguration![](/images/permalink.svg)
Fields
- response_type string? - Specifies the response format. You can either choose
geojson
orjson
.
- routing ClusterConfigurationRouting? -
- clustering ClusterConfigurationClustering? -
graphhopper.directions: ClusterConfigurationClustering![](/images/permalink.svg)
Fields
- num_clusters int? - Specifies the number of clusters
- max_quantity int? - Specifies max. quantity in a cluster
- min_quantity int? - Specifies min. quantity in a cluster
graphhopper.directions: ClusterConfigurationRouting![](/images/permalink.svg)
Fields
- cost_per_second float? - Cost per second (travel time)
- cost_per_meter float? - Cost per meter (travel distance)
graphhopper.directions: ClusterCustomer![](/images/permalink.svg)
Fields
- id string? - id of customer
- address ClusterCustomerAddress? -
- quantity int? - demand of customer
graphhopper.directions: ClusterCustomerAddress![](/images/permalink.svg)
Fields
- lon float? - Longitude
- lat float? - Latitude
- 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.
graphhopper.directions: ClusterRequest![](/images/permalink.svg)
Fields
- configuration ClusterConfiguration? -
- customers ClusterCustomer[]? -
graphhopper.directions: ClusterResponse![](/images/permalink.svg)
Fields
- copyrights string[]? -
- status string? - Indicates the current status of the job
- waiting_time_in_queue float? -
- processing_time float? -
- clusters Cluster[]? -
graphhopper.directions: Configuration![](/images/permalink.svg)
Specifies general configurations that are taken into account when solving the vehicle routing problem.
Fields
- routing Routing? - This contains all routing specific configurations.
graphhopper.directions: ConnectionConfig![](/images/permalink.svg)
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings? - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings? - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- poolConfig PoolConfiguration? - Configurations associated with request pooling
- cache CacheConfig? - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker CircuitBreakerConfig? - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig? - Configurations associated with retrying
- responseLimits ResponseLimitConfigs? - Configurations associated with inbound response size limits
- secureSocket ClientSecureSocket? - SSL/TLS-related options
- proxy ProxyConfig? - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
graphhopper.directions: CostMatrix![](/images/permalink.svg)
Fields
- 'type string? - type of cost matrix, currently default or google are supported
- location_ids string[]? -
- data CostmatrixData? - JSON data of matrix response
- profile string? - vehicle profile or empty if catch all fallback
graphhopper.directions: CostmatrixData![](/images/permalink.svg)
JSON data of matrix response
Fields
- times int[]? - Times values
- distances decimal[]? - Distances
- info CostmatrixDataInfo? - Additional information for your request
graphhopper.directions: CostmatrixDataInfo![](/images/permalink.svg)
Additional information for your request
Fields
- copyrights string[]? - Copyright details
- took float? - Took value
graphhopper.directions: Detail![](/images/permalink.svg)
Fields
- id string? - Id of unassigned service/shipment
- code int? - Reason code Code | Reason :------|:--------- 1 | cannot serve required skill 2 | cannot be visited within time window 3 | does not fit into any vehicle due to capacity 4 | cannot be assigned due to max distance constraint of vehicles 21 | could not be assigned due to relation constraint 22 | could not be assigned due to allowed vehicle constraint 23 | could not be assigned due to max-time-in-vehicle constraint 24 | driver does not need a break 25 | could not be assigned due to disallowed vehicle constraint 26 | could not be assigned due to max drive time constraint 27 | could not be assigned due to max job constraint 28 | could not be assigned due to max activity constraint 50 | underlying location cannot be accessed over road network by at least one vehicle
- reason string? - Human readable reason as listed above
graphhopper.directions: DriveTimeBreak![](/images/permalink.svg)
Fields
- duration int - Specifies the duration of the break in seconds.
- max_driving_time int - Specifies the max driving time (in a row) without break in seconds.
- initial_driving_time int? - Specifies the initial (current) driving time of a driver to allow dynamic adaptations in seconds.
- possible_split int[]? - Array specifying how a break duration (in seconds) can be split into several smaller breaks
graphhopper.directions: ErrorMessage![](/images/permalink.svg)
Fields
- message string? - error message
- details string? - Details
graphhopper.directions: GeocodingLocation![](/images/permalink.svg)
Fields
- point GeocodingPoint? -
- osm_id string? - The OSM ID of the entity
- osm_type string? - N = node, R = relation, W = way
- osm_key string? - The OSM key of the entity
- name string? - The name of the entity. Can be a boundary, POI, address, etc
- country string? - The country of the address
- city string? - The city of the address
- state string? - The state of the address
- street string? - The street of the address
- housenumber string? - The housenumber of the address
- postcode string? - The postcode of the address
graphhopper.directions: GeocodingPoint![](/images/permalink.svg)
Fields
- lat float? - Latitude
- lng float? - Longitude
graphhopper.directions: GeocodingResponse![](/images/permalink.svg)
Fields
- hits GeocodingLocation[]? -
- took int? - in ms
graphhopper.directions: GHError![](/images/permalink.svg)
Fields
- message string? -
- hints GherrorHints[]? - Optional error information.
graphhopper.directions: GherrorHints![](/images/permalink.svg)
Fields
- message string? -
graphhopper.directions: GroupRelation![](/images/permalink.svg)
Fields
- 'type string - Specifies the type of relation. It must be either of type - in_sequence or in_direct_sequence.
- groups string[] - An array of groups that should be related
graphhopper.directions: InfoResponse![](/images/permalink.svg)
Information about the server and the geographical area that it covers.
Fields
- 'version string? - The version of the GraphHopper server that provided this response. This is not related to the API version.
- bbox string? - The bounding box of the geographical area covered by this GraphHopper instance. Format:
"minLon,minLat,maxLon,maxLat"
- features record {}? - The supported features, such as elevation, per vehicle profile.
graphhopper.directions: InlineResponse404![](/images/permalink.svg)
Fields
- message string? - Error message
- status string? - status
graphhopper.directions: InternalErrorMessage![](/images/permalink.svg)
Fields
- code int? -
- message string? - Details
graphhopper.directions: IsochroneResponse![](/images/permalink.svg)
Fields
- polygons IsochroneResponsePolygon[]? - The list of polygons in GeoJson format. It can be used e.g. in the Leaflet framework:
The number of polygon is identical to the specified buckets in the query. Every polygon contains the bucket number in the properties section of the GeoJson.L.geoJson(json.polygons).addTo(map)
- copyrights string[]? -
graphhopper.directions: IsochroneResponsePolygon![](/images/permalink.svg)
A found path
Fields
- properties IsochroneresponsepolygonProperties? - Polygon properties
- 'type string? - Type detail
- geometry Polygon? - Polygon details
graphhopper.directions: IsochroneresponsepolygonProperties![](/images/permalink.svg)
Polygon properties
Fields
- bucket int? - Bucket detail
graphhopper.directions: JobId![](/images/permalink.svg)
Fields
- job_id string? - UUID. Unique id for your job/request with which you can fetch your solution
graphhopper.directions: JobRelation![](/images/permalink.svg)
Fields
- 'type string - Specifies the type of relation. It must be either of type -
in_same_route
,in_sequence
orin_direct_sequence
.in_same_route
: As the name suggest, it enforces the specified services or shipments to be in the same route. It can be specified as follows:
This enforces service i to be in the same route as service j no matter which vehicle will be employed. If a specific vehicle (driver) is required to conduct this, just add a{ "type": "in_same_route", "ids": ["serv_i_id","serv_j_id"] }
vehicle_id
like this:
This not only enforce service i and j to be in the same route, but also makes sure that both services are in the route of{ "type": "in_same_route", "ids": ["serv_i_id","serv_j_id"], "vehicle_id": "vehicle1" }
vehicle1
. Tip: This way initial loads and vehicle routes can be modelled. For example, if your vehicles are already on the road and new orders come in, then vehicles can still be rescheduled subject to the orders that have already been assigned to these vehicles.in_sequence
: This relation type enforces n jobs to be in sequence. It can be specified as
which means that service j need to be in the same route as service i AND it needs to occur somewhere after service i. As described above if a specific vehicle needs to conduct this, just add{ "type": "in_sequence", "ids": ["serv_i_id","serv_j_id"] }
vehicle_id
.in_direct_sequence
: This enforces n services or shipments to be in direct sequence. It can be specified as
yielding service j to occur directly after service i, and service k to occur directly after service j i.e. in strong order. Again, a vehicle can be assigned a priority by adding a{ "type": "in_direct_sequence", "ids": ["serv_i_id","serv_j_id","serv_k_id"] }
vehicle_id
to the relation. Special IDs: If you look at the previous example and you want service i to be the first in the route, use the special IDstart
as follows:
Latter enforces the direct sequence of i, j and k at the beginning of the route. If this sequence should be bound to the end of the route, use the special ID{ "type": "in_direct_sequence", "ids": ["start","serv_i_id","serv_j_id","serv_k_id"] }
end
like this:
If you deal with services then you need to use the 'id' of your services in the field 'ids'. To also consider sequences of the pickups and deliveries of your shipments, you need to use a special ID, i.e. use the shipment id plus the keyword{ "type": "in_direct_sequence", "ids": ["serv_i_id","service_j_id","serv_k_id","end"] }
_pickup
or_delivery
. For example, to ensure that the pickup and delivery of the shipment with the id 'my_shipment' are direct neighbors, you need the following specification:{ "type": "in_direct_sequence", "ids": ["my_ship_pickup","my_ship_delivery"] }
- ids string[] - 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 IDstart
. In turn, useend
to place it at the end of the route.
- vehicle_id string? - Id of pre-assigned vehicle, i.e. the vehicle id that is determined to conduct the services and shipments in this relation.
graphhopper.directions: LineString![](/images/permalink.svg)
Fields
- 'type string? -
- coordinates decimal[]? - A list of coordinate pairs or triples,
[lon,lat]
or[lon,lat,elevation]
.
graphhopper.directions: MatrixRequest![](/images/permalink.svg)
Fields
- from_points decimal[]? - 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 onefrom_point
parameter and threeto_point
parameters.
- to_points decimal[]? - The destination points for the routes in an array of
[longitude,latitude]
.
- from_point_hints string[]? - See
point_hints
of symmetrical matrix
- to_point_hints string[]? - See
point_hints
of symmetrical matrix
- snap_preventions string[]? - See
snap_preventions
of symmetrical matrix
- from_curbsides string[]? - See
curbsides
of symmetrical matrix
- to_curbsides string[]? - See
curbsides
of symmetrical matrix
- out_arrays string[]? - 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 ofdistances
are meters, oftimes
are seconds and ofweights
is arbitrary and it can differ for different vehicles or versions of this API.
- fail_fast boolean? - 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 thenull
value for all entries that could not be calculated. Thehint
field of the response will also contain additional information about what went wrong (see its documentation).
- turn_costs boolean? - Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
graphhopper.directions: MatrixResponse![](/images/permalink.svg)
Fields
- distances decimal[]? - 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 containnull
for connections that could not be found.
- times decimal[]? - 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 containnull
for connections that could not be found.
- weights decimal[]? - 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 containnull
for connections that could not be found.
- info ResponseInfo? - Additional information for your request
- hints MatrixresponseHints[]? - Optional. Additional response data.
graphhopper.directions: MatrixresponseHints![](/images/permalink.svg)
Fields
- message string? - Short description of this hint
- details string? - Details of this hint
- invalid_from_points decimal[]? - Optional. An array of from_point indices of points that could not be found. Will only be added if
fail_fast=false
and somefrom_point
s were not found.
- invalid_to_points decimal[]? - Optional. An array of to_point indices of points that could not be found. Will only be added if
fail_fast=false
and someto_point
s were not found.
- point_pairs decimal[]? - 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.
graphhopper.directions: Objective![](/images/permalink.svg)
Fields
- 'type string - Type of objective function, i.e.
min
ormin-max
.min
: Minimizes the objective value.min-max
: Minimizes the maximum objective value.
min
->vehicles
minimizes the number of employed vehicles.min
->completion_time
minimizes the sum of your vehicle routes' completion time. If you use, for example,min-max
->completion_time
, it minimizes the maximum of your vehicle routes' completion time, i.e. it minimizes the overall makespan. This only makes sense if you have more than one vehicle. In case of one vehicle, switching frommin
tomin-max
should not have any impact. If you have more than one vehicle, then the algorithm tries to constantly move stops from one vehicle to another such that the completion time of longest vehicle route can be further reduced. For example, if you have one vehicle that takes 8 hours to serve all customers, adding another vehicle (and usingmin-max
) might halve the time to serve all customers to 4 hours. However, this usually comes with higher transport costs. If you want to minimizevehicles
first and, second,completion_time
, you can also combine different objectives like this:
If you want to balance activities or the number of stops among all employed drivers, you need to specify it as follows:"objectives" : [ { "type": "min", "value": "vehicles" }, { "type": "min", "value": "completion_time" } ]
"objectives" : [ { "type": "min-max", "value": "completion_time" }, { "type": "min-max", "value": "activities" } ]
- value string - The value of the objective function.
The objective value
transport_time
solely considers the time your drivers spend on the road, i.e. transport time. In contrary totransport_time
,completion_time
also takes waiting times at customer sites into account. Thecompletion_time
of a route is defined as the time from starting to ending the route, i.e. the route's transport time, the sum of waiting times plus the sum of activity durations. Note that choosingtransport_time
orcompletion_time
only makes a difference if you specified time windows for your services/shipments since only in scenarios with time windows waiting times can occur. The objective valuevehicles
can only be used along withmin
and minimizes vehicles.
graphhopper.directions: Pickup![](/images/permalink.svg)
Fields
- Fields Included from *Stop
- address Address
- duration int
- preparation_time int
- time_windows TimeWindow[]
- group string
- anydata...
graphhopper.directions: Polygon![](/images/permalink.svg)
Polygon details
Fields
- 'type string? - Type
- coordinates decimal[]? - Coordinates
graphhopper.directions: ProxyConfig![](/images/permalink.svg)
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password
graphhopper.directions: Request![](/images/permalink.svg)
Fields
- vehicles Vehicle[]? - Specifies the available vehicles.
- vehicle_types VehicleType[]? - Specifies the available vehicle types. These types can be assigned to vehicles.
- services Service[]? - Specifies the orders of the type "service". These are, for example, pick-ups, deliveries or other stops that are to be approached by the specified vehicles. Each of these orders contains only one location.
- shipments Shipment[]? - Specifies the available shipments. Each shipment contains a pickup and a delivery stop, which must be processed one after the other.
- relations JobRelation|GroupRelation[]? - Defines additional relationships between orders.
- algorithm Algorithm? - Use
objectives
instead.
- objectives Objective[]? - Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized.
- cost_matrices CostMatrix[]? - Specifies your own tranport time and distance matrices.
- configuration Configuration? - Specifies general configurations that are taken into account when solving the vehicle routing problem.
graphhopper.directions: Response![](/images/permalink.svg)
Fields
- copyrights string[]? -
- status string? - Indicates the current status of the job
- waiting_time_in_queue int? - Waiting time in ms
- processing_time int? - Processing time in ms. If job is still waiting in queue, processing_time is 0
- solution Solution? - Only available if status field indicates
finished
.
graphhopper.directions: ResponseAddress![](/images/permalink.svg)
Address of activity
Fields
- location_id string? - Specifies the id of the location.
- name string? - Name of location.
- lon float? - Longitude of location.
- lat float? - Latitude 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.
- snapped_waypoint SnappedWaypoint? - Access point to the (road)network. It is only available if
return_snapped_waypoints
is true (be default it is false).
graphhopper.directions: ResponseInfo![](/images/permalink.svg)
Additional information for your request
Fields
- copyrights string[]? - Attribution according to our documentation is necessary if no white-label option included.
- took float? - Took value
graphhopper.directions: Route![](/images/permalink.svg)
Fields
- vehicle_id string? - Id of vehicle that operates route
- distance int? - Distance of route in meter
- transport_time int? - Transport time of route in seconds
- completion_time int? - Completion time of route in seconds
- waiting_time int? - Waiting time of route in seconds
- service_duration int? - Service duration of route in seconds
- preparation_time int? - Preparation time of route in seconds
- activities Activity[]? - Array of activities
- points RoutePoint[]? - Array of route planning points
graphhopper.directions: RoutePoint![](/images/permalink.svg)
Fields
- 'type string? -
- coordinates record {}[]? -
graphhopper.directions: RouteRequest![](/images/permalink.svg)
Fields
- points decimal[]? - 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 C then you specifypoints: [ [A_longitude, A_latitude], [B_longitude, B_latitude], [C_longitude, C_latitude]]
- point_hints string[]? - 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.
- snap_preventions string[]? - Optional parameter to avoid snapping to a certain road class or road environment. Current supported values
motorway
,trunk
,ferry
,tunnel
,bridge
andford
- curbsides string[]? - Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.
- locale string? - The locale of the resulting turn instructions. E.g.
pt_PT
for Portuguese orde
for German.
- elevation boolean? - If
true
, a third coordinate, the altitude, is included with all positions in the response. This changes the format of thepoints
andsnapped_waypoints
fields of the response, in both their encodings. Unless you switch off thepoints_encoded
parameter, you need special code on the client side that can handle three-dimensional coordinates. A request can fail if the vehicle profile does not support elevation. See the features object for every vehicle profile.
- optimize string? - Normally, the calculated route will visit the points in the order you specified them.
If you have more than two points, you can set this parameter to
"true"
and the points may be re-ordered to minimize the total travel time. Keep in mind that the limits on the number of locations of the Route Optimization API applies, and the request costs more credits.
- instructions boolean? - If instructions should be calculated and returned
- calc_points boolean? - If the points for the route should be calculated at all.
- debug boolean? - If
true
, the output will be formatted.
- points_encoded boolean? - Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact
but requires special client code to unpack. (We provide it in our JavaScript client library!)
Set this parameter to
false
to switch the encoding to simple coordinate pairs like[lon,lat]
, or[lon,lat,elevation]
. See the description of the response format for more information.
- 'ch\.disable boolean? - Use this parameter in combination with one or more parameters from below.
- weighting string? - Determines the way the ''best'' route is calculated. Default is
fastest
. Other options areshortest
(e.g. forvehicle=foot
orbike
) andshort_fastest
which finds a reasonable balance betweenshortest
andfastest
. Requiresch.disable=true
.
- headings int[]? - Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points.
In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.
This parameter also influences the tour generated with
algorithm=round_trip
and forces the initial direction. Requiresch.disable=true
.
- heading_penalty int? - Time penalty in seconds for not obeying a specified heading. Requires
ch.disable=true
.
- pass_through boolean? - If
true
, u-turns are avoided at via-points with regard to theheading_penalty
. Requiresch.disable=true
.
- block_area string? - Block road access via a point with the format
latitude,longitude
or an area defined by a circlelat,lon,radius
or a rectanglelat1,lon1,lat2,lon2
. Separate several values with;
. Requiresch.disable=true
.
- avoid string? - Specify which road classes and environments you would like to avoid.
Possible values are
motorway
,steps
,track
,toll
,ferry
,tunnel
andbridge
. Separate several values with;
. Obviously not all the values make sense for all vehicle profiles e.g.bike
is already forbidden on amotorway
. Requiresch.disable=true
.
- algorithm string? - Rather than looking for the shortest or fastest path, this lets you solve two different problems related to routing:
With
round_trip
, the route will get you back to where you started. This is meant for fun (think of a bike trip), so we will add some randomness. This requiresch.disable=true
. Withalternative_route
, we give you not one but several routes that are close to optimal, but not too similar to each other. You can control both of these features with additional parameters, see below.
- 'round\_trip\.distance int? - If
algorithm=round_trip
, this parameter configures approximative length of the resulting round trip. Requiresch.disable=true
.
- 'round\_trip\.seed int? - If
algorithm=round_trip
, this sets the random seed. Change this to get a different tour for each value.
- 'alternative\_route\.max\_paths int? - If
algorithm=alternative_route
, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives.
- 'alternative\_route\.max\_weight\_factor decimal? - 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.
- 'alternative\_route\.max\_share\_factor decimal? - If
algorithm=alternative_route
, this parameter specifies how similar an alternative route can be to the optimal route. Increasing can lead to worse alternatives.
graphhopper.directions: RouteResponse![](/images/permalink.svg)
Fields
- paths RouteResponsePath[]? -
- info ResponseInfo? - Additional information for your request
graphhopper.directions: RouteResponsePath![](/images/permalink.svg)
Fields
- distance float? - The total distance, in meters. To get this information for one 'leg' please read this blog post.
- time int? - The total travel time, in milliseconds. To get this information for one 'leg' please read this blog post.
- ascend float? - The total ascent, in meters.
- descend float? - The total descent, in meters.
- points record {}? -
- snapped_waypoints record {}? -
- points_encoded boolean? - Whether the
points
andsnapped_waypoints
fields are polyline-encoded strings rather than JSON arrays of coordinates. See the field description for more information on the two formats.
- bbox decimal[]? - The bounding box of the route geometry. Format:
[minLon, minLat, maxLon, maxLat]
.
- instructions RouteresponsepathInstructions[]? - The instructions for this route. This feature is under active development, and our instructions can sometimes be misleading, so be mindful when using them for navigation.
- details record {}? - Details, as requested with the
details
parameter. Consider the value{"street_name": [[0,2,"Frankfurter Straße"],[2,6,"Zollweg"]]}
. In this example, the route uses two streets: The first, Frankfurter Straße, is used betweenpoints[0]
andpoints[2]
, and the second, Zollweg, betweenpoints[2]
andpoints[6]
. See here for discussion.
- points_order int[]? - An array of indices (zero-based), specifiying the order in which the input points are visited.
Only present if the
optimize
parameter was used.
graphhopper.directions: RouteresponsepathInstructions![](/images/permalink.svg)
Fields
- text string? - A description what the user has to do in order to follow the route. The language depends on the locale parameter.
- street_name string? - The name of the street to turn onto in order to follow the route.
- distance float? - The distance for this instruction, in meters.
- time int? - The duration for this instruction, in milliseconds.
- interval int[]? - Two indices into
points
, referring to the beginning and the end of the segment of the route this instruction refers to.
- sign int? - A number which specifies the sign to show: | sign | description | |---|---| |-98| an U-turn without the knowledge if it is a right or left U-turn | | -8| a left U-turn | | -7| keep left | | -6| not yet used: leave roundabout | | -3| turn sharp left | | -2| turn left | | -1| turn slight left | | 0| continue on street | | 1| turn slight right | | 2| turn right | | 3| turn sharp right | | 4| the finish instruction before the last point | | 5| the instruction before a via point | | 6| the instruction before entering a roundabout | | 7| keep right | | 8| a right U-turn | | *| For future compatibility it is important that all clients are able to handle also unknown instruction sign numbers
- exit_number int? - Only available for roundabout instructions (sign is 6). The count of exits at which the route leaves the roundabout.
- turn_angle float? - Only available for roundabout instructions (sign is 6). The radian of the route within the roundabout
0 < r < 2*PI
for clockwise and-2*PI < r < 0
for counterclockwise turns.
graphhopper.directions: Routing![](/images/permalink.svg)
This contains all routing specific configurations.
Fields
- calc_points 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.
- consider_traffic boolean? - indicates whether historical traffic information should be considered
- curbside_strictness string? - 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
tosoft
to ignore the curbside constraint in such cases or set it tostrict
to get an error response instead. You can also set it toignore
to ignore all curbside constraints (this is useful to compare the results with and without constraints without modifying every single address).
- fail_fast boolean? - indicates whether matrix calculation should fail fast when points cannot be connected
- return_snapped_waypoints 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.
- snap_preventions string[]? - Prevents snapping locations to road links of specified road types, e.g. to motorway.
graphhopper.directions: Service![](/images/permalink.svg)
Fields
- id string - Specifies the id of the service. Ids need to be unique so there must not be two services/shipments with the same id.
- 'type string? - 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
orpickup
, 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 adelivery
, 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).
- priority int? - 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.
- name string? - Meaningful name for service, e.g.
"deliver pizza"
.
- address Address? -
- duration int? - Specifies the duration of the service in seconds, i.e. how long it takes at the customer site.
- preparation_time int? - 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.
- time_windows TimeWindow[]? - 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.
- size int[]? - 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.
- required_skills string[]? - 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 ascrew_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 skillsdrilling_machine
ANDscrew_driver
in its skill array. Otherwise it remains unassigned.
- allowed_vehicles string[]? - 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
ORtechnician_stefan
specify this as follows:["technician_peter","technician_stefan"]
.
- disallowed_vehicles string[]? - Specifies an array of disallowed vehicles, i.e. array of vehicle ids.
- max_time_in_vehicle int? - Specifies the maximum time in seconds a delivery can stay in the vehicle. Currently, it only works with services of "type":"delivery".
graphhopper.directions: Shipment![](/images/permalink.svg)
Fields
- id string - Specifies the id of the shipment. Ids need to be unique so there must not be two services/shipments with the same id.
- name string? - Meaningful name for shipment, e.g. "pickup and deliver pizza to Peter".
- priority int? - 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.
- pickup Stop -
- delivery Stop -
- size int[]? - 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.
- required_skills string[]? - 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 ascrew_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 skillsdrilling_machine
ANDscrew_driver
in its skill array. Otherwise it remains unassigned.
- allowed_vehicles string[]? - 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"].
- disallowed_vehicles string[]? - Specifies an array of disallowed vehicles, i.e. array of vehicle ids.
- max_time_in_vehicle int? - Specifies the maximum time in seconds a shipment can stay in the vehicle.
graphhopper.directions: SnappedWaypoint![](/images/permalink.svg)
Access point to the (road)network. It is only available if return_snapped_waypoints
is true (be default it is false).
Fields
- lon float? - Longitude of location.
- lat float? - Latitude of location.
graphhopper.directions: Solution![](/images/permalink.svg)
Only available if status field indicates finished
.
Fields
- costs int? - The cost
- distance int? - Overall distance travelled in meter, i.e. the sum of each route's transport distance
- time int? - Use
transport_time
instead.
- transport_time int? - Overall time travelled in seconds, i.e. the sum of each route's transport time.
- max_operation_time int? - Operation time of longest route in seconds.
- waiting_time int? - Overall waiting time in seconds.
- service_duration int? - Overall service time in seconds.
- preparation_time int? - Overall preparation time in seconds.
- completion_time int? - Overall completion time in seconds, i.e. the sum of each routes/drivers operation time.
- no_vehicles int? - Number of employed vehicles.
- no_unassigned int? - Number of jobs that could not be assigned to final solution.
- routes Route[]? - An array of routes
- unassigned SolutionUnassigned? - Unassigned details
graphhopper.directions: SolutionUnassigned![](/images/permalink.svg)
Unassigned details
Fields
- services string[]? - An array of ids of unassigned services
- shipments string[]? - An array of ids of unassigned shipments
- breaks string[]? - An array of ids of unassigned breaks
- details Detail[]? - An array of details, i.e. reason for unassigned services or shipments
graphhopper.directions: Stop![](/images/permalink.svg)
Fields
- address Address? -
- duration int? - Specifies the duration of the pickup or delivery in seconds, e.g. how long it takes unload items at the customer site.
- preparation_time int? - 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.
- time_windows TimeWindow[]? - Specifies an array of time window objects (see time window object below). For example, if an item needs to be delivered between 7am and 10am then specify the array as follows: [ { "earliest": 25200, "latest" : 32400 } ] (starting the day from 0 in seconds).
graphhopper.directions: SymmetricalMatrixRequest![](/images/permalink.svg)
Fields
- points decimal[]? - Specify multiple points for which the weight-, route-, time- or distance-matrix should be calculated as follows:
[longitude,latitude]
. In this case the origins are identical to the destinations. Thus, if there are N points, NxN entries are calculated. The order of the point parameter is important. Specify at least three points. Cannot be used together withfrom_point
orto_point.
.
- point_hints string[]? - 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.
- snap_preventions string[]? - Optional parameter to avoid snapping to a certain road class or road environment. Current supported values
motorway
,trunk
,ferry
,tunnel
,bridge
andford
- curbsides string[]? - 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.
- out_arrays string[]? - 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 ofdistances
are meters, oftimes
are seconds and ofweights
is arbitrary and it can differ for different vehicles or versions of this API.
- fail_fast boolean? - 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 thenull
value for all entries that could not be calculated. Thehint
field of the response will also contain additional information about what went wrong (see its documentation).
- turn_costs boolean? - Specifies if turn restrictions should be considered. Enabling this option increases the matrix computation time. Only supported for motor vehicles and OpenStreetMap.
graphhopper.directions: TimeWindow![](/images/permalink.svg)
Fields
- earliest int? - Specifies the opening time of the time window in seconds, i.e. the earliest time the service can start.
- latest int? - Specifies the closing time of the time window in seconds, i.e. the latest time the service can start.
graphhopper.directions: TimeWindowBreak![](/images/permalink.svg)
Fields
- earliest int - Specifies the earliest start time of the break in seconds.
- latest int - Specifies the latest start time of break in seconds.
- duration int - Specifies the duration of the break in seconds.
graphhopper.directions: Vehicle![](/images/permalink.svg)
Fields
- vehicle_id string - Specifies the ID of the vehicle. Ids must be unique, i.e. if there are two vehicles with the same ID, an error is returned.
- type_id string? - The type ID assigns a vehicle type to this vehicle. You can specify types in the array of vehicle types. If you omit the type ID, the default type is used. The default type is a
car
with a capacity of 0.
- start_address Address -
- end_address Address? -
- 'break TimeWindowBreak|DriveTimeBreak? -
- return_to_depot boolean? - If it is false, the algorithm decides where to end the vehicle route. It ends in one of your customers' locations. The end is chosen such that it contributes to the overall objective function, e.g. min transport_time. If it is true, you can either specify a specific end location (which is then regarded as end depot) or you can leave it and the driver returns to its start location.
- earliest_start int? - Earliest start of vehicle in seconds. It is recommended to use the unix timestamp.
- latest_end int? - Latest end of vehicle in seconds, i.e. the time the vehicle needs to be at its end location at latest.
- skills string[]? - Array of skills, i.e. array of string (not case sensitive).
- max_distance int? - Specifies the maximum distance (in meters) a vehicle can go.
- max_driving_time int? - Specifies the maximum drive time (in seconds) a vehicle/driver can go, i.e. the maximum time on the road (service and waiting times are not included here)
- max_jobs int? - Specifies the maximum number of jobs a vehicle can load.
- min_jobs int? - Specifies the minimum number of jobs a vehicle should load. This is a soft constraint, i.e. if it is not possible to fulfill “min_jobs”, we will still try to get as close as possible to this constraint.
- max_activities int? - Specifies the maximum number of activities a vehicle can conduct.
- move_to_end_address boolean? - Indicates whether a vehicle should be moved even though it has not been assigned any jobs.
graphhopper.directions: VehicleType![](/images/permalink.svg)
Fields
- type_id string - Specifies the id of the vehicle type. If a vehicle needs to be of this type, it should refer to this with its type_id attribute.
- profile string? - Specifies the vehicle profile of this type. The profile is used to determine the network, speed and other physical attributes to use for routing the vehicle.
- capacity int[]? - Specifies an array of capacity dimension values which need to be int values. For example, if there are two dimensions such as volume and weight then it needs to be defined as [ 1000, 300 ] assuming a maximum volume of 1000 and a maximum weight of 300.
- speed_factor float? - Specifies a speed factor for this vehicle type. If the vehicle that uses this type needs to be only half as fast as what is actually calculated with our routing engine then set the speed factor to 0.5.
- service_time_factor float? - Specifies a service time factor for this vehicle type. If the vehicle/driver that uses this type is able to conduct the service as double as fast as it is determined in the corresponding service or shipment then set it to 0.5.
- cost_per_meter float? - BETA feature! Cost parameter per distance unit, here meter is used
- cost_per_second float? - BETA feature! Cost parameter per time unit, here second is used
- cost_per_activation float? - BETA feature! Cost parameter vehicle activation, i.e. fixed costs per vehicle
- consider_traffic boolean? - Specifies whether traffic should be considered. if "tomtom" is used and this is false, free flow travel times from "tomtom" are calculated. If this is true, historical traffic info are used. We do not yet have traffic data for "openstreetmap", thus, setting this true has no effect at all.
- network_data_provider string? - Specifies the network data provider. Either use
openstreetmap
(default) ortomtom
(add-on required).
Union types![](/images/permalink.svg)
graphhopper.directions: MatrixBody![](/images/permalink.svg)
MatrixBody
graphhopper.directions: MatrixCalculateBody![](/images/permalink.svg)
MatrixCalculateBody
String types![](/images/permalink.svg)
graphhopper.directions: EncodedLineString![](/images/permalink.svg)
EncodedLineString
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.
graphhopper.directions: VehicleProfileId![](/images/permalink.svg)
VehicleProfileId
Import
import ballerinax/graphhopper.directions;
Metadata
Released date: over 1 year ago
Version: 1.5.1
License: Apache-2.0
Compatibility
Platform: any
Ballerina version: 2201.4.1
GraalVM compatible: Yes
Pull count
Total: 0
Current verison: 0
Weekly downloads
Keywords
IT Operations/Cloud Services
Cost/Freemium
Contributors
Dependencies