graphhopper.directions
Module graphhopper.directions
API
Definitions
ballerinax/graphhopper.directions Ballerina library
Overview
GraphHopper Directions API provides route planning, turn-by-turn navigation, route optimization, isochrone calculation, geocoding, matrix calculation, map matching, location clustering and custom routing profiles for building location-aware applications.
The GraphHopper Directions connector lets Ballerina integrations call these services through a typed client. It supports version 1.0.0 of the GraphHopper Directions API and authenticates with an API key.
Key features
- Calculate routes between two or more points with turn-by-turn instructions
- Compute travel time and distance matrices, synchronously or as asynchronous jobs
- Solve vehicle routing and clustering problems for delivery and service fleets
- Generate isochrones that show the area reachable within a time or distance limit
- Search addresses and places with forward and reverse geocoding
- Map-match GPX tracks and manage custom routing profiles
Setup guide
To use the GraphHopper Directions connector, you need an API key.
-
Sign up for GraphHopper or log in to your existing account.
-
Open the GraphHopper dashboard and create an API key by following the API key guide.
-
Copy the generated key and keep it safe. The connector sends it as the
keyquery parameter in every request.
Quickstart
To use the graphhopper.directions connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
import ballerinax/graphhopper.directions;
Step 2: Instantiate a new connector
- Create a
Config.tomlfile and configure the obtained API key as follows:
apiKey = "<Your GraphHopper API Key>"
- Create a
directions:ApiKeysConfigand initialize the client.
configurable string apiKey = ?; final directions:Client graphhopper = check new ({'key: apiKey});
Step 3: Invoke the connector operation
Calculate a route between two points:
public function main() returns error? { directions:RouteResponse _ = check graphhopper->getRoute(point = ["52.517037,13.388860", "52.525439,13.413000"], profile = "car"); }
Step 4: Run the Ballerina application
bal run
Examples
The GraphHopper Directions connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
- Route travel planner - Geocode two addresses, calculate the car route between them and compute the area reachable from the origin.
- Delivery route optimization - Submit a delivery optimization job for a van and poll until the optimized route is ready.
Clients
graphhopper.directions: Client
GraphHopper Directions API for A-to-B route planning, turn-by-turn navigation, route optimization, isochrone calculations, map matching, geocoding and location clustering.
Constructor
Gets invoked to initialize the connector.
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
function getRoute(map<string|string[]> headers, *GetRouteQueries queries) returns RouteResponse|errorCalculate a route
Parameters
- queries *GetRouteQueries - Queries to be sent with the request
Return Type
- RouteResponse|error - Routing Result
calculateRoute
function calculateRoute(RouteRequest payload, map<string|string[]> headers) returns RouteResponse|errorCalculate a route
Parameters
- payload RouteRequest - Route calculation request with points, profile and routing options
Return Type
- RouteResponse|error - Routing Result
getIsochrone
function getIsochrone(map<string|string[]> headers, *GetIsochroneQueries queries) returns IsochroneResponse|errorCompute an isochrone
Parameters
- queries *GetIsochroneQueries - Queries to be sent with the request
Return Type
- IsochroneResponse|error - Isochrone Result
getMatrix
function getMatrix(map<string|string[]> headers, *GetMatrixQueries queries) returns MatrixResponse|errorCompute a matrix
Parameters
- queries *GetMatrixQueries - Queries to be sent with the request
Return Type
- MatrixResponse|error - Matrix API response
calculateMatrix
function calculateMatrix(MatrixBody payload, map<string|string[]> headers) returns MatrixResponse|errorCompute a matrix
Parameters
- payload MatrixBody - Matrix calculation request with points, profile and requested outputs
Return Type
- MatrixResponse|error - Matrix API response
submitMatrixJob
function submitMatrixJob(MatrixCalculateBody payload, map<string|string[]> headers) returns JobId|errorSubmit a matrix computation job
Parameters
- payload MatrixCalculateBody - Matrix calculation job request with points, profile and requested outputs
getMatrixSolution
function getMatrixSolution(string jobId, map<string|string[]> headers) returns MatrixJobResponse|errorRetrieve result of a matrix computation job
Parameters
- jobId string - The jobId you received when you submitted the job
Return Type
- MatrixJobResponse|error - A response containing the matrix
matchGpx
function matchGpx(xml payload, map<string|string[]> headers, *MatchGpxQueries queries) returns RouteResponse|errorMap-match a GPX file
Parameters
- payload xml - A GPX document containing the map-matching input
- queries *MatchGpxQueries - Queries to be sent with the request
Return Type
- RouteResponse|error - Map matching result
getGeocode
function getGeocode(map<string|string[]> headers, *GetGeocodeQueries queries) returns GeocodingResponse|errorGeocoding Endpoint
Parameters
- queries *GetGeocodeQueries - Queries to be sent with the request
Return Type
- GeocodingResponse|error - An array found locations
solveVrp
function solveVrp(OptimizationRequest payload, map<string|string[]> headers) returns OptimizationResponse|errorSolve a route optimization problem
Parameters
- payload OptimizationRequest - The request that contains the vehicle routing problem to be solved
Return Type
- OptimizationResponse|error - A response containing the solution
submitVrpJob
function submitVrpJob(OptimizationRequest payload, map<string|string[]> headers) returns JobId|errorSubmit a route optimization job
Parameters
- payload OptimizationRequest - The request that contains the problem to be solved
Return Type
getVrpSolution
function getVrpSolution(string jobId, map<string|string[]> headers) returns OptimizationResponse|errorRetrieve solution of a route optimization job
Parameters
- jobId string - Request solution with jobId
Return Type
- OptimizationResponse|error - A response containing the solution
solveClustering
function solveClustering(ClusterRequest payload, map<string|string[]> headers) returns ClusterResponse|errorSolve a clustering problem
Parameters
- payload ClusterRequest - Request object that contains the problem to be solved
Return Type
- ClusterResponse|error - A response containing the solution
submitClusteringJob
function submitClusteringJob(ClusterRequest payload, map<string|string[]> headers) returns JobId|errorSubmit a clustering job
Parameters
- payload ClusterRequest - Request object that contains the problem to be solved
Return Type
getClusteringSolution
function getClusteringSolution(string jobId, map<string|string[]> headers) returns ClusterResponse|errorRetrieve solution of a clustering job
Parameters
- jobId string - Request solution with jobId
Return Type
- ClusterResponse|error - A response containing the solution
listProfiles
function listProfiles(map<string|string[]> headers) returns ProfileGetResponse|errorList your custom routing profiles
Return Type
- ProfileGetResponse|error - Your profiles
createProfile
function createProfile(ProfileRequest payload, map<string|string[]> headers) returns ProfileResponse|errorCreate a custom routing profile
Parameters
- payload ProfileRequest - Custom routing profile definition with base profile and custom model
Return Type
- ProfileResponse|error - Profile created
submitProfileJob
Submit a profile creation job
Parameters
- payload ProfileRequest - Custom routing profile definition to be processed as a job
getProfileSolution
function getProfileSolution(string jobId, map<string|string[]> headers) returns ProfileJobResponse|errorRetrieve result of a profile creation job
Parameters
- jobId string - The jobId you received when you submitted the job
Return Type
- ProfileJobResponse|error - A response containing the custom profile
deleteProfile
function deleteProfile(string profileId, map<string|string[]> headers) returns DeleteProfileResponse|errorDelete a custom routing profile
Parameters
- profileId string - The profile to delete
Return Type
- DeleteProfileResponse|error - A response containing the status
Records
graphhopper.directions: Activity
Fields
- setupTime? int - Setup time at this activity in seconds. Setup time is charged when the location differs from the previous activity, representing location overhead like dock check-in or security clearance
- address? ResponseAddress - Address of activity
- arrDateTime? string - Translation of unix timestamp in
arr_timeto arrival date time string with zone offset. It will be in the following ISO-8601 format: 2007-12-03T10:15:30+01:00
- distance? int - Cumulative distance from start to this activity in meters
- waitingTime? 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.earliesta waiting time oftime_window_earliest-arr_timeoccurs
- drivingTime? int - Cumulative driving time from start to this activity in seconds
- endTime? 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_timeat end)end_timeat each activity is equal to the departure time at the activity location
- departureWindow? ActivityDepartureWindow -
- 'type? "start"|"end"|"service"|"pickupShipment"|"deliverShipment"|"pickup"|"delivery"|"break" - type of activity
- priority? Signed32 - Priority copied from the underlying service or shipment (1 = highest, 10 = lowest, default 2). Omitted for
start/endactivities
- locationId? string - Id that refers to address
- loadAfter? Signed32[] - Array with size/capacity dimensions after this activity
- endDateTime? string - Translation of unix timestamp in
end_timeto end date time string with zone offset. It will be in the following ISO-8601 format: 2007-12-03T10:15:30+01:00
- timeWindow? TimeWindow -
- name? string - Human-readable name copied from the underlying service or shipment, if one was set on the request. Omitted for
start/endactivities and when the request did not specify a name
- preparationTime? int - preparation time at this activity in seconds
- loadBefore? Signed32[] - Array with size/capacity dimensions before this activity
- arrTime? int - Arrival time at this activity in seconds. If type is
start, this is not available (since it makes no sense to havearr_timeat start). However,end_timeis available and actually means "departure time" at start location. It is important to note thatarr_timedoes 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_timeis equal to activity start time
- id? string - Id referring to the underlying service or shipment, i.e. the shipment or service this activity belongs to
- group? string - Group identifier copied from the underlying activity (pickup or delivery side for shipments). Omitted for
start/endactivities and when the request did not specify a group
graphhopper.directions: ActivityDepartureWindow
The feasible departure window for the start activity. Only present on start activities when the vehicle has latest_start set. Shows the earliest and latest feasible departure times. (beta)
Fields
- earliest? int - Earliest feasible departure time in seconds
- latest? int - Latest feasible departure time in seconds
graphhopper.directions: Address
Fields
- streetHint? string - Optional parameter. Specifies a hint containing the street name to better snap the coordinates (lon,lat) to the road network. For example, if an address or building has two or more neighboring streets, you can control which street is used to find the closest location
- name? string - Name of location
- curbside "right"|"left"|"any" (default "any") - Optional parameter. Specifies on which side a point should be relative to the driver when they leave/arrive at a start/target/via point. Only supported for motor vehicles and OpenStreetMap.
If you would like to arrive at this address without having to cross the street, use
curbside=right/leftfor countries with right/left-hand driving. Usingcurbside=anyis the same as not specifying this parameter at all
- lon decimal - Longitude of location
- locationId string - Specifies the id of the location
- lat decimal - Latitude of location
graphhopper.directions: Algorithm
Use objectives instead
Fields
- problemType? "min"|"min-max" -
- objective? "transport_time"|"completion_time" -
Deprecated
graphhopper.directions: ApiKeysConfig
Provides API key configurations needed when communicating with a remote HTTP endpoint.
Fields
- 'key string - GraphHopper API key supplied as the key query parameter
graphhopper.directions: BBox
Fields
- bbox? decimal[] - A rectangular area given as an array [minLon, minLat, maxLon, maxLat]. The created profile will only work in this area. The maximum area size is 160 000 square kilometers
graphhopper.directions: Cluster
Fields
- quantity? decimal - Cluster size
- ids? string[] - Array of customer ids assigned to this specific cluster
graphhopper.directions: ClusterConfiguration
Fields
- routing? ClusterConfigurationRouting -
- responseType string(default "json") - Specifies the response format. You can either choose
geojsonorjson
- clustering? ClusterConfigurationClustering -
graphhopper.directions: ClusterConfigurationClustering
Fields
- maxQuantity? decimal - Specifies max. quantity in a cluster
- minQuantity? decimal - Specifies min. quantity in a cluster
- numClusters? decimal - Specifies the number of clusters
graphhopper.directions: ClusterConfigurationRouting
Fields
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- costPerSecond? decimal - Cost per second (travel time)
- costPerMeter? decimal - Cost per meter (travel distance)
graphhopper.directions: ClusterCustomer
Fields
- address? ClusterCustomerAddress -
- quantity? decimal - demand of customer
- id? string - id of customer
graphhopper.directions: ClusterCustomerAddress
Fields
- streetHint? string - Optional parameter. Provide a hint that includes only the street name 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
- lon? decimal - Longitude
- lat? decimal - Latitude
graphhopper.directions: ClusterRequest
Fields
- configuration? ClusterConfiguration -
- customers? ClusterCustomer[] -
- clusters? Clusters[] -
graphhopper.directions: ClusterResponse
Fields
- waitingTimeInQueue? decimal -
- processingTime? decimal -
- copyrights? string[] -
- clusters? Cluster[] -
- status? "waiting_in_queue"|"processing"|"finished" - Indicates the current status of the job
graphhopper.directions: Clusters
Fields
- maxQuantity? decimal - Specifies max. quantity of this cluster
- minQuantity? decimal - Specifies min. quantity of this cluster
- center? ClusterCustomerAddress -
- name? string - id of customer
graphhopper.directions: Configuration
Specifies general configurations that are taken into account when solving the vehicle routing problem
Fields
- routing? Routing - This contains all routing specific configurations
- optimization? Optimization - This contains all optimization specific configurations
graphhopper.directions: ConnectionConfig
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(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - 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
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
graphhopper.directions: CostMatrix
Fields
- data? CostMatrixData - JSON data of matrix response
- locationIds? string[] -
- profile? string - Vehicle profile, or empty for a catch-all fallback
- 'type? "default"|"google" - Type of cost matrix. Currently "default" and "google" are supported
graphhopper.directions: CostMatrixData
JSON data of matrix response
Fields
- distances? decimal[][] -
- times? int[][] -
- info? CostMatrixDataInfo - Additional information for your request
graphhopper.directions: CostMatrixDataInfo
Additional information for your request
Fields
- took? decimal -
- copyrights? string[] -
graphhopper.directions: CustomModel
The custom_model modifies the routing behaviour of the specified profile. See the detailed documentation.
Below is a complete request example in Berlin that limits all speeds to 100km/h, excludes motorways and makes shorter routes a bit more likely than the default due to a higher distance_influence.
Note that it also includes the "ch.disable": true parameter which is required to make use of custom_model.
{ "points": [ [ 13.31543, 52.509535 ], [ 13.29779, 52.512434 ] ], "profile": "car", "ch.disable": true, "custom_model": { "speed": [ { "if": "true", "limit_to": "100" } ], "priority": [ { "if": "road_class == MOTORWAY", "multiply_by": "0" } ], "distance_influence": 100 } }
Fields
- areas? FeatureCollection - A GeoJSON FeatureCollection. For
boundsthetypeis optional and every feature must be a Polygon
- priority? record {}[] - See priority customization
- speed? record {}[] - See speed customization
graphhopper.directions: CustomModelForProfile
The custom_model modifies the routing behaviour of the given profile. See the detailed documentation.
Here is a complete example that limits all speeds to 100km/h, avoids motorways and makes shorter routes a bit more likely than the default due to a higher distance_influence.
{ "speed": [ { "if": "true", "limit_to": 100 } ], "priority": [ { "if": "road_class == MOTORWAY", "multiply_by": 0.1 } ], "distance_influence": 100 } ``` INVALID[ ]
Fields
- areas? record {} - Areas are given in a GeoJson format. Currently only one format is supported: one object with type Feature, a geometry with type Polygon and optional (but ignored) id and properties fields. See more details and an example here
- priority? record {}[] - See priority customization
- speed? record {}[] - See speed customization
graphhopper.directions: DeleteProfileResponse
Fields
- status? "success" -
graphhopper.directions: Detail
Fields
- reason? string - Human readable reason as listed above (most likely reason)
- code? Signed32 - Reason code (most likely reason). See
reasonsarray for additional probable reasons. 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 29 | could not be assigned due to group relation constraint 30 | could not be assigned due to driving time break 31 | could not be assigned due to max service time constraint 32 | could not be assigned due to max working time constraint 33 | could not be assigned due to max route duration constraint 50 | underlying location cannot be accessed over road network by at least one vehicle 51 | location is isolated and cannot reach any other location over road network
- reasons? ReasonEntry[] - Array of probable reasons why this job could not be assigned, sorted by likelihood (most likely first).
This provides more context than the single
code/reasonfields, which only show the most likely reason. For example, a job might fail due to a relation constraint (code 21), but the underlying cause could be a time window violation (code 2). In this case, both reasons would appear in this array
- id? string - Id of unassigned service/shipment
graphhopper.directions: DriveTimeBreak
Fields
- duration int - Specifies the duration of the break in seconds
- initialDrivingTime? int - Specifies the initial (current) driving time of a driver to allow dynamic adaptations in seconds
- possibleSplit? int[] - Array specifying how a break duration (in seconds) can be split into several smaller breaks
- maxDrivingTime int - Specifies the max driving time (in a row) without break in seconds
graphhopper.directions: FeatureCollection
A GeoJSON FeatureCollection. For bounds the type is optional and every feature must be a Polygon
Fields
- features? FeatureCollectionFeatures[] - A FeatureCollection is an array of type "Feature" from GeoJSON
- 'type? "FeatureCollection" -
graphhopper.directions: FeatureCollectionFeatures
Fields
- geometry? Polygon -
- 'type? "Feature" -
graphhopper.directions: GeocodingLocation
Fields
- osmId? int - The OSM ID of the entity
- osmType? string - N = node, R = relation, W = way
- country? string - The country of the address
- osmKey? string - The OSM key of the entity
- city? string - The city of the address
- housenumber? string - The housenumber of the address
- street? string - The street of the address
- name? string - The name of the entity. Can be a boundary, POI, address, etc
- postcode? string - The postcode of the address
- state? string - The state of the address
- point? GeocodingPoint -
graphhopper.directions: GeocodingPoint
Fields
- lng? decimal - Longitude
- lat? decimal - Latitude
graphhopper.directions: GeocodingResponse
Fields
- hits? GeocodingLocation[] -
- took? decimal - in ms
graphhopper.directions: GetGeocodeQueries
Represents the Queries record for the operation: getGeocode
Fields
- q? string - A textual description of the address you are looking for. Required for forward geocoding. Note that the
defaultgeocoding provider does prefix searches preferable for "autocomplete" use cases, but may lead to sub-optimal results if used without user interaction. See e.g.provider=nominatimas an appropriate alternative for less interactive use cases
- debug boolean(default false) - If
true, the output will be formatted
- provider string(default "default") - The provider parameter is currently under development and can fall back to
defaultat 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 theproviderparameter 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_idandosm_typeare 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 support autocompletion of partial search strings. All providers support normal "forward" geocoding and reverse geocoding viareverse=true.Default (
This provider returns results of our internal geocoding engine. It is best suited for use cases with user interaction as it does prefix searches required for an "autocomplete" use case (a user types an address into a search field). In addition to the above documented parameters the following parameters are possible:provider=default)osm_tag- you can filterkey:valueor exclude places with certain OpenStreetMap tags!key:value. E.g.osm_tag=tourism:museumor just the keyosm_tag=tourism. To exclude multiple tags you add multipleosm_tagparameters.location_bias_scale- describes how much the prominence of a result should still be taken into account. Sensible values go from 0.0 (ignore prominence almost completely) to 1.0 (prominence has approximately the same influence as the location). The default is 0.2.zoom- describes the radius around the center to focus on. This is a number that should correspond roughly to the map zoom parameter of a corresponding map. The default is zoom=16.bbox- the expected format isminLon,minLat,maxLon,maxLat. This requires reverse=false.radius- the search radius in km for the reverse search. This requires reverse=true.
Nominatim (
The GraphHopper Directions API uses a commercially hosted Nominatim geocoder (hosted by OpenCageData). It is best suited for use cases without or less user interaction like batch processing or detailed location data retrieval. It is not suited for "autocomplete". In addition to the above documented parameters we currently support the following parameters:provider=nominatim)- 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 is
minLon,minLat,maxLon,maxLat
Gisgraphy (
This provider returns results from the Gisgraphy geocoder which you can try here. Limitations: Theprovider=gisgraphy)localeparameter 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 meterscountry- restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country.
OpenCage Data (
This provider returns results from the OpenCageData geocoder which you can try here. The difference to theprovider=opencagedata)nominatimprovider is that other geocoders might be used under the hood. 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 is
minLon,minLat,maxLon,maxLat
- 'limit Signed32(default 5) - Specify the maximum number of results to return
- locale string(default "en - for the default provider") - Display the search results for the specified
locale. For the default geocoding provideren,fr,es,de,pt,ruanditare supported. Otherwise leave the locale empty
- reverse boolean(default false) - It is
requiredto betrueif you want to do a reverse geocoding request. If it istrue,pointmust be defined as well, andqmust not be used
- 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
graphhopper.directions: GetIsochroneQueries
Represents the Queries record for the operation: getIsochrone
Fields
- distanceLimit? Signed32 - Specify which distance the vehicle should travel. In meters
- timeLimit Signed32(default 600) - Specify which time the vehicle should travel. In seconds
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- buckets Signed32(default 1) - Number by which to divide the given
time_limitto createbucketsnested isochrones of time intervalstime_limit-n*time_limit/buckets. Applies analogously todistance_limit
- reverseFlow boolean(default false) - If
falsethe flow goes from point to the polygon, iftruethe 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.
- point string - Specify the start coordinate
graphhopper.directions: GetMatrixQueries
Represents the Queries record for the operation: getMatrix
Fields
- pointHint? string[] - Optional parameter. Specifies a hint for each
pointparameter 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
- toPointHint? string[] - For the to_point parameter. See point_hint
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- 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
falsethe time/weight/distance matrix will be calculated for all valid points and contain thenullvalue for all entries that could not be calculated. Thehintfield of the response will also contain additional information about what went wrong (see its documentation)
- curbside? ("any"|"right"|"left")[] - 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
- snapPrevention? string[] - Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the
pointparameter. Thesnap_preventionparameter allows you to prevent snapping to specific types of roads. For example, ifsnap_preventionis set to bridge, the routing engine will avoid snapping to a bridge, even if it is the closest road for the givenpoint. Current supported values:motorway,trunk,ferry,tunnel,bridgeandford. Multiple values are specified likesnap_prevention=ferry&snap_prevention=motorway. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use thecustom_model
- point? string[] - Specify multiple points in
latitude,longitudefor 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
- toCurbside? ("any"|"right"|"left")[] - Curbside setting for the to_point parameter. See curbside
- outArray? string[] - 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
- toPoint? string[] - The destination points for the routes in
latitude,longitude
- fromCurbside? ("any"|"right"|"left")[] - Curbside setting for the from_point parameter. See curbside
- fromPoint? string[] - The origin 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
- fromPointHint? string[] - For the from_point parameter. See point_hint
graphhopper.directions: GetRouteQueries
Represents the Queries record for the operation: getRoute
Fields
- elevation boolean(default false) - If
true, a third coordinate, the altitude, is included with all positions in the response. This changes the format of thepointsandsnapped_waypointsfields of the response, in both their encodings. Unless you switch off thepoints_encodedparameter, you need special code on the client side that can handle three-dimensional coordinates
- instructions boolean(default true) - If instructions should be calculated and returned
- pointHint? string[] - The
point_hintis typically a road name to which the associatedpointparameter should be snapped to. Specify nopoint_hintparameter or the same number as you havepointparameters
- debug boolean(default false) - If
true, the output will be formatted
- 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
- heading? Signed32[] - 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_tripand forces the initial direction. Requiresch.disable=true
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- passThrough boolean(default false) - If
true, u-turns are avoided at via-points with regard to theheading_penalty. Requiresch.disable=true
- curbside? ("any"|"right"|"left")[] - 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
- roundTripSeed? int - If
algorithm=round_trip, this sets the random seed. Change this to get a different tour for each value
- locale string(default "en") - The locale of the resulting turn instructions. E.g.
pt_PTfor Portuguese ordefor German
- 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
- snapPrevention? string[] - Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the
pointparameter. Thesnap_preventionparameter allows you to prevent snapping to specific types of roads. For example, ifsnap_preventionis set to bridge, the routing engine will avoid snapping to a bridge, even if it is the closest road for the givenpoint. Current supported values:motorway,trunk,ferry,tunnel,bridgeandford. Multiple values are specified likesnap_prevention=ferry&snap_prevention=motorway. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use thecustom_model
- 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
falseto switch the encoding to simple coordinate pairs like[lon,lat], or[lon,lat,elevation]. See the description of the response format for more information
- 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
- 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. If you set it to "true" then it cannot be used withch.disable: true. If you still want to use the custom model with route optimization, then you'll need to use the Profiles API
- chDisable boolean(default false) - Use
trueto enable the flexible mode to use thecustom_modelor any of the following options below
- roundTripDistance Signed32(default 10000) - If
algorithm=round_trip, this parameter configures approximative length of the resulting round trip
- calcPoints boolean(default true) - If the points for the route should be calculated at all
- details? string[] - Optional parameter. The following path details are available:
street_name,street_ref,street_destination,leg_time,leg_distance,roundabout,country,time,distance,max_speed,max_weight,max_width,toll,road_class,road_class_link,road_access,road_environment,hazmat,hazmat_tunnel,hazmat_water,lanes,surface,smoothness,hike_rating,mtb_rating,foot_network,bike_network. Read more about the usage of path details here
- alternativeRouteMaxPaths Signed32(default 2) - If
algorithm=alternative_route, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives
- headingPenalty Signed32(default 300) - Time penalty in seconds for not obeying a specified heading. Requires
ch.disable=true
- algorithm? "round_trip"|"alternative_route" - 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. Limitation: works with custom_model but not with custom profiles. 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. You can control both of these features with additional parameters, see below.
graphhopper.directions: GroupRelation
Fields
- groups string[] - An array of groups that should be related
- 'type string - Specifies the type of relation. It must be either of type
in_sequence,in_direct_sequenceorneighbor
graphhopper.directions: IsochroneResponse
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 GeoJsonL.geoJson(json.polygons).addTo(map)
graphhopper.directions: IsochroneResponsePolygon
A found path
Fields
- geometry? Polygon -
- 'type? string -
- properties? IsochroneResponsePolygonProperties -
graphhopper.directions: IsochroneResponsePolygonProperties
Fields
- bucket? Signed32 -
graphhopper.directions: JobId
Fields
- jobId? string - UUID. Unique id for your job/request with which you can fetch your solution
graphhopper.directions: JobRelation
Fields
- areaRadius? decimal - Radius in meters. Required for
in_area_sequencerelations. Jobs within this road distance of an anchor job are automatically assigned to that area
- 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
_pickupor_delivery. If you want to place a service or shipment activity at the beginning of your route, use the special IDstart. In turn, useendto place it at the end of the route
- 'type string - Specifies the type of relation. It must be either of type
in_same_route,not_in_same_route,in_sequence,in_direct_sequence,neighbororin_area_sequence.in_same_route: As the name suggests, 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_idlike this:
This not only enforces service i and j to be in the same route, but also ensures 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.not_in_same_route: It ensures that 2 or more orders are not transported by the same vehicle. It can be specified as follows:{ "type": "not_in_same_route", "ids": ["serv_i_id","serv_j_id"] }in_sequence: This relation type enforces n jobs to be in sequence. It can be specified as
which means that service j needs 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 perform these services, 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
This causes service j to occur directly after service i, and service k to occur directly after service j, i.e. in strict sequence. Again, a specific vehicle can be assigned by adding a{ "type": "in_direct_sequence", "ids": ["serv_i_id","serv_j_id","serv_k_id"] }vehicle_idto the relation. When a plain shipment id (without the_pickup/_deliverysuffix described below) is used in anin_direct_sequencerelation, it stands for the whole shipment: its pickup directly followed by its delivery. For example,"ids": ["ship_1","ship_2"]enforces the strict activity sequence pickup of 1, delivery of 1, pickup of 2, delivery of 2 — with no other stops in between. If other activities should be allowed between a shipment's pickup and delivery, reference the activities individually via the_pickup/_deliverysuffixes instead.neighbor: This specifies a neighbor relationship, i.e., if services i and j are to be neighbors, i must be either immediately before or after j. It can be specified as follows:{ "type": "neighbor", "ids": ["serv_i_id","serv_j_id"] }in_area_sequence: This defines an area-level visit order. You pick one job per area as an anchor and set a radius. All other jobs within the radius of an anchor are automatically clustered into that area. Areas are visited in the specified order, and within each area the optimizer handles the details. It can be specified as follows:
This means: visit the area around{ "type": "in_area_sequence", "ids": ["job_area_a","job_area_b","job_area_c"], "area_radius": 5000 }job_area_afirst, then the area aroundjob_area_b, thenjob_area_c. Any ungrouped job within 5000 meters (road distance) of an anchor is automatically assigned to that area. Jobs outside all radii are placed wherever fits best. You can assign the area sequence to a specific vehicle:
Multiple{ "type": "in_area_sequence", "ids": ["job_area_a","job_area_b"], "area_radius": 5000, "vehicle_id": "vehicle1" }in_area_sequencerelations can be used to assign different area sequences to different vehicles. If an anchor job already has agroup, that group name is used instead of an auto-generated one, and nearby jobs are assigned to it. Special IDs: If you look at the previous example and you want service i to be the first in the route, use the special IDstartas follows:
This enforces the direct sequence of i, j, and k at the beginning of the route. If this sequence should be at the end of the route, use the special ID{ "type": "in_direct_sequence", "ids": ["start","serv_i_id","serv_j_id","serv_k_id"] }endlike 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"] }_pickupor_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"] }
- vehicleId? 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
Fields
- coordinates? decimal[][] - A list of coordinate pairs or triples,
[lon,lat]or[lon,lat,elevation]
- 'type? string -
graphhopper.directions: MatchGpxQueries
Represents the Queries record for the operation: matchGpx
Fields
- elevation boolean(default false) - If
true, a third coordinate, the altitude, is included with all positions in the response. This changes the format of thepointsandsnapped_waypointsfields of the response, in both their encodings. Unless you switch off thepoints_encodedparameter, you need special code on the client side that can handle three-dimensional coordinates
- instructions boolean(default true) - If instructions should be calculated and returned
- gpsAccuracy? int - Specify the precision of a point, in meter
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- calcPoints boolean(default true) - If the points for the route should be calculated at all
- details? string[] - Optional parameter. The following path details are available:
street_name,street_ref,street_destination,leg_time,leg_distance,roundabout,country,time,distance,max_speed,max_weight,max_width,toll,road_class,road_class_link,road_access,road_environment,hazmat,hazmat_tunnel,hazmat_water,lanes,surface,smoothness,hike_rating,mtb_rating,foot_network,bike_network. Read more about the usage of path details here
- locale string(default "en") - The locale of the resulting turn instructions. E.g.
pt_PTfor Portuguese ordefor German
- 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
falseto switch the encoding to simple coordinate pairs like[lon,lat], or[lon,lat,elevation]. See the description of the response format for more information
graphhopper.directions: MatrixJobResponse
Fields
- solution? MatrixResponse -
- status? "processing"|"finished" -
graphhopper.directions: MatrixRequest
Fields
- fromCurbsides? string[] - See
curbsidesof symmetrical matrix
- outArrays? 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 ofdistancesare meters, oftimesare seconds and ofweightsis arbitrary and it can differ for different vehicles or versions of this API
- fromPoints? decimal[][] - The origin points for the routes in an array of
[longitude,latitude]
- toPoints? decimal[][] - The destination points for the routes in an array of
[longitude,latitude]
- toCurbsides? string[] - See
curbsidesof symmetrical matrix
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- toPointHints? string[] - See
point_hintsof symmetrical matrix
- 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
falsethe time/weight/distance matrix will be calculated for all valid points and contain thenullvalue for all entries that could not be calculated. Thehintfield of the response will also contain additional information about what went wrong (see its documentation)
- snapPreventions? string[] - See
snap_preventionsof symmetrical matrix
- fromPointHints? string[] - See
point_hintsof symmetrical matrix
graphhopper.directions: MatrixResponse
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=falsethe matrix will containnullfor 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=falsethe matrix will containnullfor connections that could not be found
- hints? MatrixResponseHints[] - Optional. Additional response data
- weights? decimal[][] - The weight matrix for the specified points in the same order as the time matrix. The weights for different vehicle profiles 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=falsethe matrix will containnullfor connections that could not be found
- info? ResponseInfo - Additional information for your request
graphhopper.directions: MatrixResponseHints
Fields
- invalidFromPoints? decimal[] - Optional. An array of from_point indices of points that could not be found. Will only be added if
fail_fast=falseand somefrom_points were not found.MISSING[] MISSING[]
- details? string - Details of this hint
- pointPairs? 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=falseand some connections were not found
- message? string - Short description of this hint
- invalidToPoints? decimal[] - Optional. An array of to_point indices of points that could not be found. Will only be added if
fail_fast=falseand someto_points were not found.MISSING[] MISSING[]
graphhopper.directions: Objective
Fields
- level Signed32(default 2) - (Beta) Level for
balanceobjectives (1-3). Controls how strongly to prioritize balanced workloads.1- Accept some workload variation for better travel efficiency2- Moderate balance (default)3- Strictly equal workloads, even at cost of longer travel
typeisbalance. Ignored for other objective types
- 'type "min"|"min-max"|"balance" (default "min") - Type of objective function, i.e.
min,min-max, orbalance.min: Minimizes the objective value.min-max: Minimizes the maximum objective value.balance: (Beta) Optimizes for balanced workloads across drivers. Use withvalue: completion_timeto balance working time, orvalue: activitiesto balance the number of stops per driver.
min->vehiclesminimizes the number of employed vehicles.min->completion_timeminimizes 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 frommintomin-maxshould 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 minimizevehiclesfirst 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" } ]Balance Objective (Beta)
Thebalanceobjective type provides a more sophisticated approach to workload balancing compared tomin-max. Whilemin-maxonly minimizes the maximum route value,balanceoptimizes for equal distribution of work across all drivers by minimizing the coefficient of variation (CV) of workloads. Usebalancewith:value: completion_time- Balance working time (service time + travel time + waiting time) across driversvalue: activities- Balance the number of stops per driver
levelparameter (1-3) controls how strongly to prioritize balance:level: 1- Mild balance preference, allows some variation for better travel efficiencylevel: 2- Moderate balance (default), good trade-off between balance and efficiencylevel: 3- Strict balance, prioritizes equal workloads even at the cost of longer travel
When to use"objectives" : [ { "type": "balance", "value": "completion_time", "level": 2 } ]balancevsmin-max:- Use
balancewhen you want all drivers to have similar workloads (fairness) - Use
min-maxwhen you only care about minimizing the longest route (makespan)
balanceobjective currently only supports services. Requests that combinebalanceobjectives with shipments will return a400error
- value "completion_time"|"completion_time_last_stop"|"route_duration"|"transport_time"|"vehicles"|"activities" (default "transport_time") - The value of the objective function.
The objective value
transport_timesolely considers the time your drivers spend on the road, i.e. transport time. In contrary totransport_time,completion_timealso takes waiting times at customer sites into account. Thecompletion_timeof 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. Thecompletion_time_last_stop, on the other hand, refers to the completion time of the very last order in a tour or, in other words, the completion time without the last section from the last stop to the end of the tour. This is typically used if the orders are to be processed as quickly as possible. If you solely want to minimize route duration, you should use simply useroute_duration. The objective valuevehiclescan only be used along withminand minimizes vehicles. Forbalanceobjective type, onlycompletion_timeandactivitiesare supported
graphhopper.directions: Optimization
This contains all optimization specific configurations
Fields
- freeInsertion boolean(default false) - If you use groups, you sometimes want to place orders without group assignment in the best position, i.e. sometimes in the middle of a group and not before or after the group. This is not allowed by default. However, if this field here is "true", these orders (without a group assignment) can be inserted freely
- freeInsertionExemptGroups? string[] - When
free_insertionis enabled, ungrouped orders can be inserted anywhere, including inside groups. Use this property to specify groups where ungrouped orders should NOT be inserted. This is useful when you have groups like "asap" (must be served first) or "last" (must be served last) that should stay compact. For example, withfree_insertion_exempt_groups: ["asap", "last"], ungrouped orders can be inserted freely between other groups, but not inside the "asap" or "last" groups, and not between start and "asap" or between "last" and end when usingin_direct_sequencerelations with these groups
- autoAssignRadius decimal(default 0) - Radius in meters. When set to a positive value, ungrouped jobs are automatically assigned to the nearest existing group based on road distance. This is useful when you use groups and group-level
in_sequenceto define an area visit order, and want new jobs to automatically cluster into the right area. Jobs outside the radius of all groups remain ungrouped. Requiresfree_insertion: truefor ungrouped jobs to be placed freely
graphhopper.directions: OptimizationRequest
Fields
- vehicleTypes? VehicleType[] - Specifies the available vehicle types. These types can be assigned to vehicles
- configuration? Configuration - Specifies general configurations that are taken into account when solving the vehicle routing problem
- vehicles? Vehicle[] - Specifies the available vehicles
- objectives? Objective[] - Specifies an objective function. The vehicle routing problem is solved in such a way that this objective function is minimized
- services? Service[] - Specifies the orders of the type "service". These are, for example, pickups, deliveries, or other stops to be visited by the specified vehicles. Each of these orders contains only one location
- relations? RequestRelations[] - Defines additional relationships between orders
- shipments? Shipment[] - Specifies the available shipments. Each shipment consists of a pickup and a delivery. For a single shipment, the pickup must always occur before the delivery. However, pickups and deliveries from multiple shipments can be sequenced independently
- costMatrices? CostMatrix[] - Specifies your own transport time and distance matrices
- algorithm? Algorithm - Use
objectivesinstead
graphhopper.directions: OptimizationResponse
Fields
- waitingTimeInQueue? int - Waiting time in milliseconds
- processingTime? int - Processing time in ms. If job is still waiting in queue, processing_time is 0
- solution? OptimizationSolution - Only available if status field indicates
finished
- copyrights? string[] -
- status? "waiting_in_queue"|"processing"|"finished" - Indicates the current status of the job
graphhopper.directions: OptimizationSolution
Only available if status field indicates finished
Fields
- costs? Signed32 -
- setupTime? int - Overall setup time in seconds
- completionTime? int - Overall completion time in seconds, i.e. the sum of each route's operation time
- distance? Signed32 - Overall distance traveled in meters, i.e. the sum of each route's transport distance
- transportTime? int - Overall time travelled in seconds, i.e. the sum of each route's transport time
- waitingTime? int - Overall waiting time in seconds
- unassigned? SolutionUnassigned -
- serviceDuration? int - Overall service time in seconds
- routes? Route[] - An array of routes
- noVehicles? Signed32 - Number of employed vehicles
- preparationTime? int - Overall preparation time in seconds
- time? int - Use
transport_timeinstead
- noUnassigned? Signed32 - Number of jobs that could not be assigned to final solution
- maxOperationTime? int - Operation time of longest route in seconds
graphhopper.directions: Polygon
Fields
- coordinates? decimal[][][] -
- 'type? "Polygon" -
graphhopper.directions: PreferredVehicle
Fields
- priority int(default 2) - Number between 1 and 10 which indicates the priority of the preferred vehicle. 1 indicates the highest priority, 10 the lowest
- vehicleId? string - Id of the preferred vehicle
graphhopper.directions: ProfileJobResponse
Fields
- solution? ProfileResponse -
- status? "processing"|"finished" -
graphhopper.directions: ProfileRequest
Fields
- profile? "foot"|"bike"|"ecargobike"|"car"|"small_truck"|"truck"|"scooter" - The built-in profile your new custom profile shall be based on
- bounds? BBox|FeatureCollection - The area of the profile, either a rectangle (
bbox) or polygons (features)
- customModel? CustomModelForProfile -
graphhopper.directions: ProfileResponse
Fields
- profile? string - The built-in profile this custom profile is based on
- bounds? BBox|FeatureCollection - The area of the profile as specified in the request
- customModel? CustomModelForProfile -
- id? string - The name of the created profile. Use this as the
profileparameter for the /route API etc. For route optimization requests you need to define a vehicle_type where you can enter the custom profile
graphhopper.directions: ReasonEntry
A single reason entry with code and human-readable description
Fields
- reason? string - Human readable reason
- code? Signed32 - Reason code (see Detail.code for the full list of codes)
graphhopper.directions: ResponseAddress
Address of activity
Fields
- streetHint? 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
- name? string - Name of location
- snappedWaypoint? SnappedWaypoint -
- lon? decimal - Longitude of location
- locationId? string - Specifies the id of the location
- lat? decimal - Latitude of location
graphhopper.directions: ResponseInfo
Additional information for your request
Fields
- took? decimal -
- copyrights? string[] - Attribution according to our documentation is necessary if no white-label option included
graphhopper.directions: Route
Fields
- setupTime? int - Setup time of route in seconds
- completionTime? int - Completion time of route in seconds
- distance? int - Distance of route in meters
- transportTime? int - Transport time of route in seconds
- waitingTime? int - Waiting time of route in seconds
- activities? Activity[] - Array of activities
- preparationTime? int - Preparation time of route in seconds
- vehicleId? string - Id of vehicle that operates route
- serviceDuration? int - Service duration of route in seconds
- points? RoutePoints[] - One entry for every vehicle
graphhopper.directions: RouteRequest
Fields
- elevation boolean(default false) - If
true, a third coordinate, the altitude, is included with all positions in the response. This changes the format of thepointsandsnapped_waypointsfields of the response, in both their encodings. Unless you switch off thepoints_encodedparameter, you need special code on the client side that can handle three-dimensional coordinates
- instructions boolean(default true) - If instructions should be calculated and returned
- debug boolean(default false) - If
true, the output will be formatted
- 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
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- passThrough boolean(default false) - If
true, u-turns are avoided at via-points with regard to theheading_penalty. Requiresch.disable=true
- customModel? CustomModel -
- roundTripSeed? int - If
algorithm=round_trip, this sets the random seed. Change this to get a different tour for each value
- snapPreventions? ("motorway"|"trunk"|"bridge"|"ford"|"tunnel"|"ferry")[] - Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the
pointsarray. Thesnap_preventionsarray allows you to prevent snapping to specific types of roads. For example, if the array includesbridge, then the routing engine will avoid snapping to a bridge, even if it is the closest road for the given point. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use thecustom_model
- locale string(default "en") - The locale of the resulting turn instructions. E.g.
pt_PTfor Portuguese ordefor German
- 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
- 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
falseto switch the encoding to simple coordinate pairs like[lon,lat], or[lon,lat,elevation]. See the description of the response format for more information
- pointHints? string[] - Optional parameter. Specifies a hint for each point in the
pointsarray 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. Make sure you do not include the house number of city name and only the street name to improve the quality of the matching
- points? decimal[][] - The query points used to calculate the route, requiring at least a start and a destination point, with optional via-points in between
- 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
- chDisable boolean(default false) - Use
trueto enable the flexible mode to use thecustom_modelor any of the following options below
- roundTripDistance Signed32(default 10000) - If
algorithm=round_trip, this parameter configures approximative length of the resulting round trip
- calcPoints boolean(default true) - If the points for the route should be calculated at all
- headings? Signed32[] - 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 headings parameter also influences the tour generated with
algorithm=round_tripand forces the initial direction. Requiresch.disable=true
- details? string[] - Optional parameter. The following path details are available:
street_name,street_ref,street_destination,leg_time,leg_distance,roundabout,country,time,distance,max_speed,max_weight,max_width,toll,road_class,road_class_link,road_access,road_environment,hazmat,hazmat_tunnel,hazmat_water,lanes,surface,smoothness,hike_rating,mtb_rating,foot_network,bike_network. Read more about the usage of path details here
- alternativeRouteMaxPaths Signed32(default 2) - If
algorithm=alternative_route, this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives
- curbsides? ("any"|"right"|"left")[] - Optional parameter. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicle profiles and OpenStreetMap
- headingPenalty Signed32(default 300) - Time penalty in seconds for not obeying a specified heading. Requires
ch.disable=true
- algorithm? "round_trip"|"alternative_route" - 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. Limitation: works with custom_model but not with custom profiles. 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. You can control both of these features with additional parameters, see below.
graphhopper.directions: RouteResponse
Fields
- paths? RouteResponsePath[] -
- info? ResponseInfo - Additional information for your request
graphhopper.directions: RouteResponsePath
Fields
- descend? decimal - The total descent, in meters
- 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
- ascend? decimal - The total ascent, in meters
- distance? decimal - The total distance, in meters. To get this information for one 'leg' please read this blog post
- bbox? decimal[] - The bounding box of the route geometry. Format:
[minLon, minLat, maxLon, maxLat]
- pointsOrder? int[] - An array of indices (zero-based), specifiying the order in which the input points are visited.
Only present if the
optimizeparameter was used
- details? record {} - Details, as requested with the
detailsparameter. 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]. Read more about the usage of path details here
- time? int - The total travel time, in milliseconds. To get this information for one 'leg' please read this blog post
- pointsEncoded? boolean - Whether the
pointsandsnapped_waypointsfields are polyline-encoded strings rather than JSON arrays of coordinates. See the field description for more information on the two formats
- points? EncodedLineString|LineString - The geometry of the route. The format depends on the value of
points_encoded
- snappedWaypoints? EncodedLineString|LineString - The snapped input points. The format depends on the value of
points_encoded
graphhopper.directions: RouteResponsePathInstructions
Fields
- exitNumber? Signed32 - Only available for roundabout instructions (sign is 6). The count of exits at which the route leaves the roundabout
- distance? decimal - The distance for this instruction, in meters
- heading? decimal - The optional heading for this roundabout instruction
- sign? Signed32 - 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
- lastHeading? decimal - The optional last heading for this roundabout instruction
- turnAngle? decimal - Only available for roundabout instructions (sign is 6). The radian of the route within the roundabout
0 < r < 2*PIfor clockwise and-2*PI < r < 0for counterclockwise turns
- interval? Signed32[] - Two indices into
points, referring to the beginning and the end of the segment of the route this instruction refers to
- text? string - A description what the user has to do in order to follow the route. The language depends on the locale parameter
- time? Signed32 - The duration for this instruction, in milliseconds
- streetName? string - The name of the street to turn onto in order to follow the route
graphhopper.directions: Routing
This contains all routing specific configurations
Fields
- networkDataProvider "openstreetmap"|"tomtom" (default "openstreetmap") - Specifies the data provider. Read more about it here
- curbsideStrictness "ignore"|"soft"|"strict" (default "soft") - 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_strictnesstosoftto ignore the curbside constraint in such cases or set it tostrictto get an error response instead. You can also set it toignoreto ignore all curbside constraints (this is useful to compare the results with and without constraints without modifying every single address)
- failFast boolean(default false) - Indicates whether matrix calculation should fail immediately when points cannot be connected
- calcPoints boolean(default false) - 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
- considerTraffic boolean(default false) - Indicates whether historical traffic information should be considered
- returnSnappedWaypoints boolean(default false) - Indicates whether the solution should include snapped waypoints. Unlike the address coordinates, a snapped waypoint is the access point to the road network
- snapPreventions? ("motorway"|"trunk"|"bridge"|"ford"|"tunnel"|"ferry")[] - Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the
pointsarray. Thesnap_preventionsarray allows you to prevent snapping to specific types of roads. For example, if the array includesbridge, then the routing engine will avoid snapping to a bridge, even if it is the closest road for the given point. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use thecustom_model
graphhopper.directions: Service
Fields
- setupTime int(default 0) - Specifies the setup time in seconds. This is a fixed overhead charged when arriving at a new location (e.g., dock check-in, security clearance, equipment preparation). Unlike
duration, setup time is only charged once per location—if multiple consecutive activities share the same location, it is applied only to the first. The activity timeline is: arrival → preparation_time → waiting (if early) → setup_time → duration
- timeWindows? TimeWindow[] - Specifies an array of time window objects (see TimeWindow object below). Specify the time either with the recommended Unix timestamp (the number of seconds since 1970-01-01) or you can count the seconds relative to Monday morning 00:00 and define the whole week in seconds. For example, Monday 9am is represented by 9 hours * 3600 sec/hour = 32400. Wednesday 1pm corresponds to 2 days * 24 hours/day * 3600 sec/hour + 13 hours * 3600 sec/hour = 219600. See our tutorial for more information
- address? Address -
- preferredVehicles? PreferredVehicle[] - Specifies an array of preferred vehicles
- 'type "service"|"pickup"|"delivery" (default "service") - 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
serviceorpickup, 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 Signed32(default 2) - Specifies the priority. Can be 1 = high priority to 10 = low priority. Priority only affects the solution when not all services can be assigned (e.g., due to insufficient vehicle capacity, conflicting time windows, or vehicle constraints). In these cases, the optimizer preferentially assigns high-priority services and leaves low-priority services unassigned. The lower the priority, the earlier these services are omitted from the solution. When all services can be served within the given constraints, priority has no effect - all services are assigned regardless of their priority values, and the optimizer focuses solely on the specified objective (e.g., minimizing distance or number of vehicles)
- duration int(default 0) - Specifies the duration of the service in seconds, i.e. how long it takes to perform the actual service. This time is charged for each activity—if multiple services occur at the same location, their durations are summed
- size Signed32[](default [0]) - Size can have multiple dimensions and should correspond to the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimensions, volume and weight, specify it as follows: [ 20, 5 ], assuming a volume of 20 and a weight of 5
- allowedVehicles? string[] - Specifies an array of allowed vehicles, i.e. an array of vehicle IDs. For example, if this service can only be performed by EITHER
technician_peterORtechnician_stefan, specify this as follows:["technician_peter","technician_stefan"]
- requiredSkills? string[] - Specifies an array of required skills, i.e. an array of strings (not case sensitive). For example, if this service needs to be performed by a technician with a
drilling_machineand ascrew_driver, specify the array as follows:["drilling_machine","screw_driver"]. This means that the service can only be done by a vehicle (technician) that has bothdrilling_machineANDscrew_driverin its skill array. Otherwise, it remains unassigned
- disallowedVehicles? string[] - Specifies an array of disallowed vehicles, i.e. an array of vehicle IDs
- name? string - A meaningful name for the service, e.g.
"deliver pizza"
- preparationTime int(default 0) - Specifies the preparation time in seconds. This time is added after arrival and before the service can begin, modeling tasks like finding a parking spot. Preparation time is only charged once when the location differs from the previous stop—if multiple consecutive activities share the same location, it is applied only to the first
- maxTimeInVehicle? int - Specifies the maximum time in seconds a delivery can stay in the vehicle. Currently, it only works with services of "type":"delivery". Omit this field to indicate no limit
- 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
- group? string - Group this service belongs to. Orders with the same group label are treated as a contiguous cluster — they stay together as a block, but the optimizer picks the internal sequence. Groups can also be referenced in group-level relations to enforce constraints like
in_sequenceacross entire clusters
graphhopper.directions: Shift
Shift of vehicle
Fields
- 'break? TimeWindowBreak|DriveTimeBreak -
- returnToDepot boolean(default true) - If true, vehicle returns to its start location (or specified end location). If false, vehicle can end at any customer location that optimizes the objective function
- shiftId? string - A unique identifier for this vehicle's shift
- startAddress? Address -
- latestEnd? int - Latest end of vehicle in seconds, i.e. the time the vehicle needs to be at its end location at latest. Omit this field to indicate no limit
- maxServiceTime? int - Specifies the maximum on-site time (in seconds) for this shift's route, i.e. the sum of all service durations (scaled by service_time_factor) plus setup times. Driving, waiting and break times are not included. Defaults to the vehicle's max_service_time
- maxRouteDuration? int - Specifies the maximum duration (in seconds) of this shift's route, i.e. the time between the actual departure and the arrival at the end location, waiting and break times included. Defaults to the vehicle's max_route_duration
- endAddress? Address -
- earliestStart int(default 0) - Earliest start of vehicle in seconds. It is recommended to use the unix timestamp
- latestStart? int - Latest start of vehicle in seconds. If specified and greater than earliest_start, the optimizer determines the best departure time within the [earliest_start, latest_start] window to minimize waiting time. (beta)
- maxWorkingTime? int - Specifies the maximum working time (in seconds) for this shift's route: driving time (incl. preparation times) plus on-site time. Waiting and break times are not included. Defaults to the vehicle's max_working_time
- departurePreference "early"|"late" (default "late") - Controls departure preference when latest_start is set. "late" (default) departs as late as possible while meeting all time windows. "early" departs as early as possible, eliminating waiting time along the route. Ignored without latest_start. (beta)
graphhopper.directions: Shipment
Fields
- delivery Stop -
- size Signed32[](default [0]) - Size can have multiple dimensions and should correspond to the capacity dimension array of the vehicle type. For example, if the item that needs to be delivered has two size dimensions, volume and weight, specify it as follows: [ 20, 5 ], assuming a volume of 20 and a weight of 5
- allowedVehicles? string[] - Specifies an array of allowed vehicles, i.e. an array of vehicle IDs. For example, if this shipment can only be handled by EITHER "technician_peter" OR "technician_stefan", specify this as follows: ["technician_peter","technician_stefan"]
- preferredVehicles? PreferredVehicle[] - Specifies an array of preferred vehicles
- requiredSkills? string[] - Specifies an array of required skills, i.e. an array of strings (not case sensitive). For example, if this shipment needs to be handled by a technician with a
drilling_machineand ascrew_driver, specify the array as follows:["drilling_machine","screw_driver"]. This means that the shipment can only be done by a vehicle (technician) that has bothdrilling_machineANDscrew_driverin its skill array. Otherwise, it remains unassigned
- disallowedVehicles? string[] - Specifies an array of disallowed vehicles, i.e. an array of vehicle IDs
- name? string - A meaningful name for the shipment, e.g. "pick up and deliver pizza to Peter"
- pickup Stop -
- maxTimeInVehicle? int - Specifies the maximum time in seconds a shipment can stay in the vehicle. Omit this field to indicate no limit
- id string - Specifies the ID of the shipment. IDs must be unique, so there must not be two services/shipments with the same ID
- priority Signed32(default 2) - Specifies the priority. Can be 1 = high priority to 10 = low priority. Priority only affects the solution when not all shipments can be assigned (e.g., due to insufficient vehicle capacity, conflicting time windows, or vehicle constraints). In these cases, the optimizer preferentially assigns high-priority shipments and leaves low-priority shipments unassigned. The lower the priority, the earlier these shipments are omitted from the solution. When all shipments can be served within the given constraints, priority has no effect - all shipments are assigned regardless of their priority values, and the optimizer focuses solely on the specified objective (e.g., minimizing distance or number of vehicles)
graphhopper.directions: SnappedWaypoint
Access point to the road network. It is only available if return_snapped_waypoints is true (by default it is false)
Fields
- lon? decimal - Longitude of location
- lat? decimal - Latitude of location
graphhopper.directions: SolutionUnassigned
Fields
- breaks? string[] - An array of ids of unassigned breaks
- activities? Activity[] - Per-activity breakdown of every unassigned job. For each unassigned service there is exactly one entry; for each unassigned shipment there are two entries (one with
type: "pickupShipment"and one withtype: "deliverShipment"), both sharing the shipment id. Schedule-derived fields (arr_time,end_time,waiting_time,distance,driving_time,preparation_time,setup_time,load_before,load_after) are zero or omitted because the job was never placed on a route. The descriptive fieldsname,priority, andgroupare echoed from the original request when present, so consumers can render or audit unassigned stops without joining back to the request.time_windowis omitted because the solver never picked one
- details? Detail[] - An array of details, i.e. reason for unassigned services or shipments
- services? string[] - An array of ids of unassigned services
- shipments? string[] - An array of ids of unassigned shipments
graphhopper.directions: Stop
Fields
- duration int(default 0) - Specifies the duration of the pickup or delivery in seconds, e.g. how long it takes to load or unload items. This time is charged for each stop—if multiple pickups or deliveries occur at the same location, their durations are summed
- setupTime int(default 0) - Specifies the setup time in seconds. This is a fixed overhead charged when arriving at a new location (e.g., dock check-in, security clearance, equipment preparation). Unlike
duration, setup time is only charged once per location—if multiple consecutive activities share the same location, it is applied only to the first. The activity timeline is: arrival → preparation_time → waiting (if early) → setup_time → duration
- timeWindows? 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)
- address? Address -
- preparationTime int(default 0) - Specifies the preparation time in seconds. This time is added after arrival and before the pickup or delivery can begin, modeling tasks like finding a parking spot. Preparation time is only charged once when the location differs from the previous stop—if multiple consecutive activities share the same location, it is applied only to the first
- group? string - Group this stop belongs to. Orders with the same group label are treated as a contiguous cluster — they stay together as a block, but the optimizer picks the internal sequence. Groups can also be referenced in group-level relations to enforce constraints like
in_sequenceacross entire clusters
graphhopper.directions: SymmetricalMatrixRequest
Fields
- outArrays? 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 ofdistancesare meters, oftimesare seconds and ofweightsis arbitrary and it can differ for different vehicle profiles or versions of this API
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- 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
falsethe time/weight/distance matrix will be calculated for all valid points and contain thenullvalue for all entries that could not be calculated. Thehintfield of the response will also contain additional information about what went wrong (see its documentation)
- snapPreventions? ("motorway"|"trunk"|"bridge"|"ford"|"tunnel"|"ferry")[] - Optional parameter. 'Snapping' is the process of finding the closest road location for GPS coordinates provided in the
pointsarray. Thesnap_preventionsarray allows you to prevent snapping to specific types of roads. For example, if the array includesbridge, then the routing engine will avoid snapping to a bridge, even if it is the closest road for the given point. Note that once snapped the routing algorithm can still route over bridges (or the other values). To avoid this you need to use thecustom_model
- curbsides? ("right"|"left"|"any")[] - 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
- pointHints? string[] - Optional parameter. Specifies a hint for each point in the
pointsarray 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
- 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_pointorto_point.
graphhopper.directions: TimeWindow
Fields
- earliest int(default 0) - 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. Omit this field to indicate no limit
graphhopper.directions: TimeWindowBreak
Fields
- duration int - Specifies the duration of the break in seconds
- earliest int - Specifies the earliest start time of the break in seconds
- latest int - Specifies the latest start time of break in seconds
graphhopper.directions: Vehicle
Fields
- moveToEndAddress? boolean - Indicates whether a vehicle should be moved even though it has not been assigned any jobs
- 'break? TimeWindowBreak|DriveTimeBreak -
- typeId string(default "default-type") - 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
carwith a capacity of 0
- returnToDepot boolean(default true) - 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
- maxRouteDuration? int - Specifies the maximum duration (in seconds) of the vehicle's route, i.e. the time between the vehicle's actual departure from its start location and its arrival at its end location (or at its last stop if
return_to_depotis false). Unlikemax_working_time, waiting and break times count towards this limit, so it bounds the time the driver is away. Unlikelatest_end, it is measured from the actual departure: withlatest_startthe optimizer may depart later thanearliest_start, and the limit applies to the route from that later departure
- earliestStart int(default 0) - Earliest start of vehicle in seconds. It is recommended to use the unix timestamp
- latestStart? int - Latest start of vehicle in seconds. If specified and greater than earliest_start, the optimizer determines the best departure time within the [earliest_start, latest_start] window to minimize waiting time. (beta)
- maxWorkingTime? int - Specifies the maximum working time (in seconds) a vehicle/driver is allowed: driving time (incl. preparation times) plus on-site time (service durations scaled by service_time_factor plus setup times). Waiting and break times are not included. Use
max_route_durationinstead if waiting time should count towards the limit
- departurePreference "early"|"late" (default "late") - Controls departure preference when latest_start is set. "late" (default) departs as late as possible while meeting all time windows. "early" departs as early as possible, eliminating waiting time along the route. Ignored without latest_start. (beta)
- skills? string[] - An array of skills, i.e. an array of strings (not case sensitive)
- minJobs? Signed32 - 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
- startAddress? Address -
- latestEnd? int - Latest end of vehicle in seconds, i.e. the time the vehicle needs to be at its end location at latest. Omit this field to indicate no limit
- maxDrivingTime? int - Specifies the maximum driving time (in seconds) a vehicle/driver is allowed, i.e. the maximum time spent on the road (service and waiting times are not included). Note that
preparation_timeof services counts as driving time
- maxServiceTime? int - Specifies the maximum on-site time (in seconds) a vehicle/driver is allowed, i.e. the sum of all service durations (scaled by the vehicle type's service_time_factor) plus setup times along the route. Driving, waiting and break times are not included
- shifts? Shift[] - An array of shift configurations for this vehicle
- endAddress? Address -
- maxActivities? Signed32 - Specifies the maximum number of activities a vehicle can conduct
- vehicleId 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
- maxDistance? int - Specifies the maximum distance (in meters) a vehicle can go
- maxJobs? Signed32 - Specifies the maximum number of jobs a vehicle can load
graphhopper.directions: VehicleType
Fields
- typeId 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
- networkDataProvider "openstreetmap"|"tomtom" (default "openstreetmap") - Specifies the network data provider. Either use
openstreetmap(default) ortomtom(add-on required)
- profile? VehicleProfileId - The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
- costPerMeter? decimal - BETA feature! Cost parameter per distance unit, here meter is used
- costPerSecond? decimal - BETA feature! Cost parameter per time unit, here second is used
- speedFactor decimal(default 1) - Specifies a speed factor for this vehicle type. For example, if a vehicle using this type should travel at half the speed calculated by our routing engine, set the speed factor to 0.5
- costPerActivation? decimal - BETA feature! Cost parameter vehicle activation, i.e. fixed costs per vehicle
- considerTraffic boolean(default false) - 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 information is used. Traffic data is not yet available for "openstreetmap", so setting this to true has no effect when using OpenStreetMap
- serviceTimeFactor decimal(default 1) - Specifies a service time factor for this vehicle type. For example, if a vehicle/driver using this type can complete services twice as fast as specified in the service or shipment, set this to 0.5
- capacity Signed32[](default [0]) - 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
Union types
graphhopper.directions: MatrixCalculateBody
MatrixCalculateBody
graphhopper.directions: MatrixBody
MatrixBody
graphhopper.directions: RequestRelations
RequestRelations
graphhopper.directions: RoutePoints
RoutePoints
The geometry of the route. The format depends on the value of points_encoded
Array types
graphhopper.directions: ProfileGetResponse
ProfileGetResponse
The existing custom profiles including their ids
String types
graphhopper.directions: VehicleProfileId
VehicleProfileId
The routing profile. It determines the network, speed and other physical attributes used when computing the route. See the section about routing profiles for more details and valid profile values
graphhopper.directions: EncodedLineString
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
Import
import ballerinax/graphhopper.directions;Metadata
Released date: about 16 hours ago
Version: 2.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-20 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 45
Current verison: 1
Weekly downloads
Keywords
Vendor/GraphHopper
Area/Developer Tools
Type/Connector
GraphHopper Directions
Contributors