Skip to content
Documentation

Optimized route

Available on the following API tiers:

Transitland v2Beta

Plan a route visiting several locations in the most efficient order, solving the traveling salesman problem. The request is the same as street routing; the service chooses the order of the locations.

GETPOSThttps://transit.land/api/v2/routing/valhalla/optimized_route

Calculate a route visiting multiple locations in the most efficient order, solving the traveling salesman problem.

Request

The request object, url-encoded. Identical to the POST body. Encode spaces as %20 rather than +, or send the JSON without spaces; a + is not decoded as a space here and the request will be rejected as unparseable.

admin_crossings
boolean
When true, the route summary includes admins (array of administrative regions the route passes through) and admin_crossings (array of objects with from_admin_index, to_admin_index, from_shape_index, and to_shape_index indicating where and along which edge an administrative boundary is crossed).
Defaultfalse
alternates
integer
Number of alternative routes to return. Forced to 0 for more than 2 waypoints.
Default0
banner_instructions
boolean
Include OSRM-format banner instructions, if format = osrm.
Defaultfalse
directions_type
string
Defaultinstructions
Enumnonemaneuversinstructions
elevation_interval
number
Elevation sample interval in meters along the path. 0 = no elevation.
Default0
linear_references
boolean
Include base64-encoded OpenLR references per edge in the response..
Defaultfalse
locations
array: object
Required
date_time
string
Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
display_lat
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
display_lon
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
heading
integer
Preferred approach heading in degrees.
heading_tolerance
integer
How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
lat
number
Required
lon
number
Required
minimum_reachability
integer
Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default50
name
string
Label echoed in the response.
node_snap_tolerance
number
Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
preferred_layer
integer
If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
preferred_side
string
Preferred side of road to snap to.
Defaulteither
Enumsameoppositeeither

Exampleopposite

radius
integer
Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
rank_candidates
boolean
Rank snap candidates by distance to input.
Defaulttrue
search_cutoff
integer
Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
search_filter
object
Optional filters to exclude candidate edges based on their attribution.
street
string
Street address hint for snapping.
street_side_cutoff
string
Enummotorwaytrunkprimarysecondarytertiaryunclassifiedresidentialservice_other

Exampleprimary

street_side_max_distance
integer
The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
street_side_tolerance
integer
If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
type
string
First and last location are always forced to break.
Defaultbreak
Enumbreakthroughviabreak_through

Examplebreak

waiting
number
Waiting time in seconds at this stop (break/break_through only, not origin/destination).
date_time
string
Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
display_lat
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
display_lon
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
heading
integer
Preferred approach heading in degrees.
heading_tolerance
integer
How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
lat
number
Required
lon
number
Required
minimum_reachability
integer
Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default50
name
string
Label echoed in the response.
node_snap_tolerance
number
Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
preferred_layer
integer
If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
preferred_side
string
Preferred side of road to snap to.
Defaulteither
Enumsameoppositeeither

Exampleopposite

radius
integer
Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
rank_candidates
boolean
Rank snap candidates by distance to input.
Defaulttrue
search_cutoff
integer
Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
search_filter
object
Optional filters to exclude candidate edges based on their attribution.
street
string
Street address hint for snapping.
street_side_cutoff
string
Enummotorwaytrunkprimarysecondarytertiaryunclassifiedresidentialservice_other

Exampleprimary

street_side_max_distance
integer
The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
street_side_tolerance
integer
If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
type
string
First and last location are always forced to break.
Defaultbreak
Enumbreakthroughviabreak_through

Examplebreak

waiting
number
Waiting time in seconds at this stop (break/break_through only, not origin/destination).
prioritize_bidirectional
boolean
Prefer bidirectional A* even when date_time.type={depart_at,arrive_by,current} in /route, or prefer CostMatrix over TDMatrix when calling /sources_to_targets
Defaultfalse
recostings
array: object
Re-score the found path under additional named costings.
alley_penalty
number
A penalty that is applied when transitioning onto an alley. Default is 60 seconds for bicycle, 5 seconds otherwise.
closure_factor
number
A factor that penalizes the cost when traversing a closed edge (eg: if search_filter.exclude_closures is false for origin and/or destination location and the route starts/ends on closed edges). Its value can range from 1.0 - don't penalize closed edges, to 10.0 - apply high cost penalty to closed edges. Default value is 9.0. Note: This factor is applicable only for motorized modes of transport, i.e auto, motorcycle, motor_scooter, bus, truck & taxi.
Default9
country_crossing_cost
number
A cost applied when encountering an international border. This cost is added to the estimated and elapsed times.
Default600
country_crossing_penalty
number
A penalty applied for a country crossing. This penalty can be used to create paths that avoid spanning country boundaries.
Default0
destination_only_penalty
number
A penalty applied when entering an road which is only allowed to enter if necessary to reach the destination.
Default600
disable_hierarchy_pruning
boolean
Disable graph hierarchy culling; if the bee-line distance between waypoints exceeds the config parameter value for service_limits.max_distance_disable_hierarchy_culling, the option is ignored
Defaultfalse
ferry_cost
number
A cost applied when entering a ferry. This cost is added to the estimated and elapsed times.
Default300
fixed_speed
integer
Fixed speed the vehicle can go in km/h. Used to override the calculated speed. Can be useful if speed of vehicle is known. Value must be between 1 and 252. The default value is 0, which disables fixed speed and falls back to the standard calculated speed based on the road attribution.
Default0
gate_cost
number
A cost applied when a gate with undefined or private access is encountered. This cost is added to estimated and elapsed times.
Default30
gate_penalty
number
A penalty applied when a gate with no access information is on the road. Default is 300 for bicycle, 30 otherwise.
ignore_access
boolean
Will ignore mode-specific access tags. Especially useful for matching GPS traces to the road network regardless of restrictions
Defaultfalse
ignore_closures
boolean
If set to true, ignores all closures, marked due to live traffic closures, during routing. Note: This option cannot be set if location.search_filter.exclude_closures is also specified in the request and will return an error if it is.
Defaultfalse
ignore_oneways
boolean
If set to true, ignores one-way restrictions. Especially useful for matching GPS traces to the road network ignoring uni-directional traffic rules. Not included in ignore_restrictions option.
Defaultfalse
ignore_restrictions
boolean
If set to true, ignores any restrictions (e.g. turn/dimensional/conditional restrictions). Especially useful for matching GPS traces to the road network regardless of restrictions.
maneuver_penalty
number
A penalty applied when transitioning between roads that do not have consistent naming — in other words, no road names in common. This penalty can be used to create simpler routes that tend to have fewer maneuvers or narrative guidance instructions. The default maneuver penalty is five seconds.
Default5
name
string
Required for recostings entries; must be unique.
private_access_penalty
number
A penalty applied when a gate or bollard with access=private is encountered. Default is 600 for pedestrian, 450 otherwise.
rail_ferry_cost
number
A cost applied when entering a rail ferry. This cost is added to the estimated and elapsed times.
Default300
service_factor
number
A factor that modifies (multiplies) the cost when generic service roads are encountered.
Default1
service_penalty
number
A penalty applied for transition to generic service road. The default penalty is 0 for trucks and pedestrian, 75 for auto/bus/taxi, 15 otherwise.
shortest
boolean
Changes the metric to quasi-shortest, i.e. purely distance-based costing. Note, this will disable all other costings & penalties. Also note, shortest will not disable hierarchy pruning, leading to potentially sub-optimal routes for some costing models.
Defaultfalse
speed_penalty_factor
number
Penalty factor applied for edges when edge speed is faster than top speed. The default value is 0.05. If you want to use top_speed without penalizing roads where the edge speed is much lower than top_speed, set this value to 0.
Default0.05
speed_types
array: string
Which speed sources to consider for computing edge cost. Defaults to all available types. Predicted, current and freeflow additionally require date_time to be set. If the array is left empty, or none of these sources are available, Valhalla will fall back to the default speed.
toll_booth_cost
number
A cost applied when a toll booth is encountered. This cost is added to the estimated and elapsed times.
Default15
toll_booth_penalty
number
A penalty applied to the cost when a toll booth is encountered. This penalty can be used to create paths that avoid toll roads.
Default0
use_ferry
number
This value indicates the willingness to take ferries. This is a range of values between 0 and 1. Values near 0 attempt to avoid ferries and values near 1 will favor ferries. Note that sometimes ferries are required to complete a route so values of 0 are not guaranteed to avoid ferries entirely.
Default0.5
use_living_streets
number
This value indicates the willingness to take living streets. This is a range of values between 0 and 1. Values near 0 attempt to avoid living streets and values near 1 will favor living streets. The default value is 0 for truck, 0.5 for bicycle, 0.6 for pedestrian, 0.1 otherwise. Note that sometimes living streets are required to complete a route so values of 0 are not guaranteed to avoid living streets entirely.
use_rail_ferry
number
This value indicates the willingness to take rail ferries. This is a range of values between 0 and 1. Values near 0 attempt to avoid rail ferries and values near 1 will favor them. Note that sometimes rail ferries may be required to complete a route so values of 0 are not guaranteed to avoid them entirely.
Default0.4
use_tracks
number
This value indicates the willingness to take track roads. This is a range of values between 0 and 1. Values near 0 attempt to avoid tracks and values near 1 will favor tracks a little bit. The default value is 0 for auto and truck, 0.5 otherwise. Note that sometimes tracks are required to complete a route so values of 0 are not guaranteed to avoid tracks entirely.
exclude_bridges
boolean
This value indicates whether or not the path may include bridges. If exclude_bridges is set to true it is allowed to start and end with bridges, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_ferries
boolean
This value indicates whether or not the path may include ferries. If exclude_ferries is set to true it is allowed to start and end with ferries, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_highways
boolean
This value indicates whether or not the path may include highways. If exclude_highways is set to true it is allowed to start and end with highways, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_tolls
boolean
This value indicates whether or not the path may include tolls. If exclude_tolls is set to true it is allowed to start and end with tolls, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_tunnels
boolean
This value indicates whether or not the path may include tunnels. If exclude_tunnels is set to true it is allowed to start and end with tunnels, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
alley_penalty
number
A penalty that is applied when transitioning onto an alley. Default is 60 seconds for bicycle, 5 seconds otherwise.
closure_factor
number
A factor that penalizes the cost when traversing a closed edge (eg: if search_filter.exclude_closures is false for origin and/or destination location and the route starts/ends on closed edges). Its value can range from 1.0 - don't penalize closed edges, to 10.0 - apply high cost penalty to closed edges. Default value is 9.0. Note: This factor is applicable only for motorized modes of transport, i.e auto, motorcycle, motor_scooter, bus, truck & taxi.
Default9
country_crossing_cost
number
A cost applied when encountering an international border. This cost is added to the estimated and elapsed times.
Default600
country_crossing_penalty
number
A penalty applied for a country crossing. This penalty can be used to create paths that avoid spanning country boundaries.
Default0
destination_only_penalty
number
A penalty applied when entering an road which is only allowed to enter if necessary to reach the destination.
Default600
disable_hierarchy_pruning
boolean
Disable graph hierarchy culling; if the bee-line distance between waypoints exceeds the config parameter value for service_limits.max_distance_disable_hierarchy_culling, the option is ignored
Defaultfalse
ferry_cost
number
A cost applied when entering a ferry. This cost is added to the estimated and elapsed times.
Default300
fixed_speed
integer
Fixed speed the vehicle can go in km/h. Used to override the calculated speed. Can be useful if speed of vehicle is known. Value must be between 1 and 252. The default value is 0, which disables fixed speed and falls back to the standard calculated speed based on the road attribution.
Default0
gate_cost
number
A cost applied when a gate with undefined or private access is encountered. This cost is added to estimated and elapsed times.
Default30
gate_penalty
number
A penalty applied when a gate with no access information is on the road. Default is 300 for bicycle, 30 otherwise.
ignore_access
boolean
Will ignore mode-specific access tags. Especially useful for matching GPS traces to the road network regardless of restrictions
Defaultfalse
ignore_closures
boolean
If set to true, ignores all closures, marked due to live traffic closures, during routing. Note: This option cannot be set if location.search_filter.exclude_closures is also specified in the request and will return an error if it is.
Defaultfalse
ignore_oneways
boolean
If set to true, ignores one-way restrictions. Especially useful for matching GPS traces to the road network ignoring uni-directional traffic rules. Not included in ignore_restrictions option.
Defaultfalse
ignore_restrictions
boolean
If set to true, ignores any restrictions (e.g. turn/dimensional/conditional restrictions). Especially useful for matching GPS traces to the road network regardless of restrictions.
maneuver_penalty
number
A penalty applied when transitioning between roads that do not have consistent naming — in other words, no road names in common. This penalty can be used to create simpler routes that tend to have fewer maneuvers or narrative guidance instructions. The default maneuver penalty is five seconds.
Default5
name
string
Required for recostings entries; must be unique.
private_access_penalty
number
A penalty applied when a gate or bollard with access=private is encountered. Default is 600 for pedestrian, 450 otherwise.
rail_ferry_cost
number
A cost applied when entering a rail ferry. This cost is added to the estimated and elapsed times.
Default300
service_factor
number
A factor that modifies (multiplies) the cost when generic service roads are encountered.
Default1
service_penalty
number
A penalty applied for transition to generic service road. The default penalty is 0 for trucks and pedestrian, 75 for auto/bus/taxi, 15 otherwise.
shortest
boolean
Changes the metric to quasi-shortest, i.e. purely distance-based costing. Note, this will disable all other costings & penalties. Also note, shortest will not disable hierarchy pruning, leading to potentially sub-optimal routes for some costing models.
Defaultfalse
speed_penalty_factor
number
Penalty factor applied for edges when edge speed is faster than top speed. The default value is 0.05. If you want to use top_speed without penalizing roads where the edge speed is much lower than top_speed, set this value to 0.
Default0.05
speed_types
array: string
Which speed sources to consider for computing edge cost. Defaults to all available types. Predicted, current and freeflow additionally require date_time to be set. If the array is left empty, or none of these sources are available, Valhalla will fall back to the default speed.
toll_booth_cost
number
A cost applied when a toll booth is encountered. This cost is added to the estimated and elapsed times.
Default15
toll_booth_penalty
number
A penalty applied to the cost when a toll booth is encountered. This penalty can be used to create paths that avoid toll roads.
Default0
use_ferry
number
This value indicates the willingness to take ferries. This is a range of values between 0 and 1. Values near 0 attempt to avoid ferries and values near 1 will favor ferries. Note that sometimes ferries are required to complete a route so values of 0 are not guaranteed to avoid ferries entirely.
Default0.5
use_living_streets
number
This value indicates the willingness to take living streets. This is a range of values between 0 and 1. Values near 0 attempt to avoid living streets and values near 1 will favor living streets. The default value is 0 for truck, 0.5 for bicycle, 0.6 for pedestrian, 0.1 otherwise. Note that sometimes living streets are required to complete a route so values of 0 are not guaranteed to avoid living streets entirely.
use_rail_ferry
number
This value indicates the willingness to take rail ferries. This is a range of values between 0 and 1. Values near 0 attempt to avoid rail ferries and values near 1 will favor them. Note that sometimes rail ferries may be required to complete a route so values of 0 are not guaranteed to avoid them entirely.
Default0.4
use_tracks
number
This value indicates the willingness to take track roads. This is a range of values between 0 and 1. Values near 0 attempt to avoid tracks and values near 1 will favor tracks a little bit. The default value is 0 for auto and truck, 0.5 otherwise. Note that sometimes tracks are required to complete a route so values of 0 are not guaranteed to avoid tracks entirely.
exclude_bridges
boolean
This value indicates whether or not the path may include bridges. If exclude_bridges is set to true it is allowed to start and end with bridges, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_ferries
boolean
This value indicates whether or not the path may include ferries. If exclude_ferries is set to true it is allowed to start and end with ferries, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_highways
boolean
This value indicates whether or not the path may include highways. If exclude_highways is set to true it is allowed to start and end with highways, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_tolls
boolean
This value indicates whether or not the path may include tolls. If exclude_tolls is set to true it is allowed to start and end with tolls, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
exclude_tunnels
boolean
This value indicates whether or not the path may include tunnels. If exclude_tunnels is set to true it is allowed to start and end with tunnels, but is not allowed to have them in the middle of the route path, otherwise they are allowed. If set to true, it is highly plausible that no path will be found.
Defaultfalse
roundabout_exits
boolean
When true, exit instructions at roundabouts are added to the output.
Defaulttrue
shape_format
string
Not all formats are supported by all endpoints, e.g. no_shape is not valid for isochrone.
Defaultpolyline6
Enumpolyline6polyline5geojsonno_shape

Examplepolyline6

turn_lanes
boolean
When true, each maneuver may include a lanes array describing lane-level guidance: possible directions and which lanes are valid or active for following the maneuver.
Defaultfalse
voice_instructions
boolean
Include OSRM-format voice instructions, if format = osrm.
Defaultfalse
costing
string
Not available here: multimodal — transit routing is served by the Transitland Routing API at /otp/plan, not by this engine.
Required
Enumautobicyclepedestriantruckbustaximotor_scootermotorcyclebikeshareauto_pedestrian

Exampleauto

costing_options
object
Costing options keyed by costing model name.
auto
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
bicycle
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
bikeshare
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
bus
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
motor_scooter
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
motorcycle
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
pedestrian
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
taxi
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
truck
object
Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
date_time
object
type
integer
0=current, 1=depart_at, 2=arrive_by, 3=invariant
Enum0123
value
string
ISO 8601 local datetime string in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06. Required for types 1, 2, 3.
exclude_locations
array: object
A set of locations to exclude or avoid within a route.
date_time
string
Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
display_lat
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
display_lon
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
heading
integer
Preferred approach heading in degrees.
heading_tolerance
integer
How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
lat
number
Required
lon
number
Required
minimum_reachability
integer
Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default50
name
string
Label echoed in the response.
node_snap_tolerance
number
Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
preferred_layer
integer
If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
preferred_side
string
Preferred side of road to snap to.
Defaulteither
Enumsameoppositeeither

Exampleopposite

radius
integer
Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
rank_candidates
boolean
Rank snap candidates by distance to input.
Defaulttrue
search_cutoff
integer
Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
search_filter
object
Optional filters to exclude candidate edges based on their attribution.
street
string
Street address hint for snapping.
street_side_cutoff
string
Enummotorwaytrunkprimarysecondarytertiaryunclassifiedresidentialservice_other

Exampleprimary

street_side_max_distance
integer
The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
street_side_tolerance
integer
If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
type
string
First and last location are always forced to break.
Defaultbreak
Enumbreakthroughviabreak_through

Examplebreak

waiting
number
Waiting time in seconds at this stop (break/break_through only, not origin/destination).
date_time
string
Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
display_lat
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
display_lon
number
Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
heading
integer
Preferred approach heading in degrees.
heading_tolerance
integer
How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
lat
number
Required
lon
number
Required
minimum_reachability
integer
Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default50
name
string
Label echoed in the response.
node_snap_tolerance
number
Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
preferred_layer
integer
If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
preferred_side
string
Preferred side of road to snap to.
Defaulteither
Enumsameoppositeeither

Exampleopposite

radius
integer
Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
rank_candidates
boolean
Rank snap candidates by distance to input.
Defaulttrue
search_cutoff
integer
Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
search_filter
object
Optional filters to exclude candidate edges based on their attribution.
street
string
Street address hint for snapping.
street_side_cutoff
string
Enummotorwaytrunkprimarysecondarytertiaryunclassifiedresidentialservice_other

Exampleprimary

street_side_max_distance
integer
The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
street_side_tolerance
integer
If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
type
string
First and last location are always forced to break.
Defaultbreak
Enumbreakthroughviabreak_through

Examplebreak

waiting
number
Waiting time in seconds at this stop (break/break_through only, not origin/destination).
exclude_polygons
array or object
Array of coordinate rings [[lon,lat],…] or a GeoJSON FeatureCollection. Roads intersecting these rings will be avoided during path finding. Takes one of the 2 forms listed below.
option 1
array: array
Array of closed coordinate rings. All edges intersecting any ring are excluded.
option 2
object
GeoJSON FeatureCollection. Each Feature may carry a properties.levels array to restrict exclusion to specific building/indoor levels in pedestrian routing.
format
string
Not all formats are supported by all endpoints, e.g. geotiff is isochrone-only.
Defaultjson
Enumjsongpxosrmpbfgeotiffmvt

Examplejson

id
string
Arbitrary request identifier echoed in the response.
language
string
BCP47 locale for narrative output. See locales/ for supported values.
Defaulten-US
linear_cost_factors
array: object
Customized cost factors that influence path finding, specified as an array of JSON objects. Objects can be either a GeoJSON linestring feature and a "factor" property or a plain object with a "shape" key, whose value needs to be an encoded polyline (with 6 digit precision), and a "factor" key whose value needs to be float. Valhalla will perform an edge walk (see the map matching documentation for more info) to match the geometry onto edges and use those factors in costing. Edges with factors larger than 1 will be increasingly avoided, while edges with factors smaller than 1 increasingly favored.
option 1
object
option 2
object
option 1
object
option 2
object
units
string
Defaultkm
Enumkmmilesmi

Example request

curl --get "https://transit.land/api/v2/routing/valhalla/optimized_route" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"costing":"auto","locations":[{"lat":37.7793,"lon":-122.4193},{"lat":37.7817,"lon":-122.4108},{"lat":37.7844,"lon":-122.4079}]}'

Response

trip
object
A route through the network, split into legs between the requested locations.
language
string
Language tag the narrative instructions are written in.

Exampleen-US

legs
array: object
One leg per consecutive pair of break locations.
locations
array: object
The requested locations, snapped to the network and in the order visited.
status
integer
Zero on success.
status_message
string
Human-readable form of status.

ExampleFound route between points

summary
object
Totals for a trip or a single leg.
units
string
Units the lengths in this trip are expressed in.
Enumkilometersmiles
warnings
array: object
Non-fatal notes about the request, such as a parameter that was ignored. Absent when there are none.

Example response

Show response
{
  "trip": {
    "language": "en-US",
    "legs": [
      {
        "maneuvers": [
          {
            "bearing_after": 352,
            "begin_shape_index": 0,
            "cost": 22.899,
            "end_shape_index": 8,
            "instruction": "Drive north on US 101 North/Van Ness Avenue.",
            "length": 0.207,
            "street_names": [
              "US 101 North",
              "Van Ness Avenue"
            ],
            "time": 20.747,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 2,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 200 meters.",
            "verbal_pre_transition_instruction": "Drive north on U.S. 1 o1 North, Van Ness Avenue. Then, in 200 meters, Turn right onto Golden Gate Avenue.",
            "verbal_succinct_transition_instruction": "Drive north. Then, in 200 meters, Turn right onto Golden Gate Avenue."
          },
          {
            "bearing_after": 81,
            "bearing_before": 351,
            "begin_shape_index": 8,
            "cost": 224.574,
            "end_shape_index": 36,
            "has_time_restrictions": true,
            "instruction": "Turn right onto Golden Gate Avenue.",
            "length": 0.845,
            "street_names": [
              "Golden Gate Avenue"
            ],
            "time": 109.411,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 10,
            "verbal_post_transition_instruction": "Continue for 800 meters.",
            "verbal_pre_transition_instruction": "Turn right onto Golden Gate Avenue.",
            "verbal_succinct_transition_instruction": "Turn right.",
            "verbal_transition_alert_instruction": "Turn right onto Golden Gate Avenue."
          },
          {
            "bearing_before": 83,
            "begin_shape_index": 36,
            "cost": 0,
            "end_shape_index": 36,
            "instruction": "Your destination is on the right.",
            "length": 0,
            "time": 0,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 5,
            "verbal_pre_transition_instruction": "Your destination is on the right.",
            "verbal_transition_alert_instruction": "Your destination will be on the right."
          }
        ],
        "shape": "{oz`gA|o|nhFwJjAuI\\}V~CiGjAuEx@cWzCeW|CyC\\SwCyIusAYaFYeEsAkS{GceAWuD_@sFkFiy@_Co^UmD_@{EsDuk@yDsl@UsD]_Fo@{IwEst@eBmXWyD]yEYoEi@sIEe@m@eJWaEsBo[i@wL",
        "summary": {
          "cost": 247.473,
          "has_ferry": false,
          "has_highway": false,
          "has_time_restrictions": true,
          "has_toll": false,
          "length": 1.053,
          "max_lat": 37.782246,
          "max_lon": -122.410884,
          "min_lat": 37.779214,
          "min_lon": -122.420355,
          "time": 130.158
        }
      },
      {
        "maneuvers": [
          {
            "bearing_after": 83,
            "begin_shape_index": 0,
            "cost": 26.928,
            "end_shape_index": 11,
            "instruction": "Drive east on Golden Gate Avenue.",
            "length": 0.123,
            "sign": {},
            "street_names": [
              "Golden Gate Avenue"
            ],
            "time": 14.284,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 2,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 100 meters.",
            "verbal_pre_transition_instruction": "Drive east on Golden Gate Avenue. Then, in 100 meters, Turn left onto Stevenson Street.",
            "verbal_succinct_transition_instruction": "Drive east. Then, in 100 meters, Turn left onto Stevenson Street."
          },
          {
            "bearing_after": 44,
            "bearing_before": 134,
            "begin_shape_index": 11,
            "cost": 94.719,
            "end_shape_index": 16,
            "instruction": "Turn left onto Stevenson Street.",
            "length": 0.277,
            "street_names": [
              "Stevenson Street"
            ],
            "time": 40.655,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 15,
            "verbal_post_transition_instruction": "Continue for 300 meters.",
            "verbal_pre_transition_instruction": "Turn left onto Stevenson Street.",
            "verbal_succinct_transition_instruction": "Turn left.",
            "verbal_transition_alert_instruction": "Turn left onto Stevenson Street."
          },
          {
            "bearing_after": 316,
            "bearing_before": 45,
            "begin_shape_index": 16,
            "cost": 55.415,
            "end_shape_index": 24,
            "instruction": "Turn left onto 5th Street.",
            "length": 0.094,
            "street_names": [
              "5th Street"
            ],
            "time": 15.95,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 90 meters.",
            "verbal_pre_transition_instruction": "Turn left onto 5th Street. Then Your destination will be on the right.",
            "verbal_succinct_transition_instruction": "Turn left. Then Your destination will be on the right.",
            "verbal_transition_alert_instruction": "Turn left onto 5th Street."
          },
          {
            "bearing_before": 315,
            "begin_shape_index": 24,
            "cost": 0,
            "end_shape_index": 24,
            "instruction": "Your destination is on the right.",
            "length": 0,
            "time": 0,
            "travel_mode": "drive",
            "travel_type": "car",
            "type": 5,
            "verbal_pre_transition_instruction": "Your destination is on the right.",
            "verbal_transition_alert_instruction": "Your destination will be on the right."
          }
        ],
        "shape": "km`agAfwjnhFe@eKB_CXeCx@wFRiBFq@Pe@hB_HvOoTdCkDzAwBsBkC}LwPomAsaB}HmKoCuDaGxH}K|NwAjBqDzEWZW^wCjEeAvA",
        "summary": {
          "cost": 177.063,
          "has_ferry": false,
          "has_highway": false,
          "has_time_restrictions": false,
          "has_toll": false,
          "length": 0.495,
          "level_changes": [
            [
              18,
              0
            ]
          ],
          "max_lat": 37.784135,
          "max_lon": -122.40748,
          "min_lat": 37.781763,
          "min_lon": -122.410884,
          "time": 70.891
        }
      }
    ],
    "locations": [
      {
        "lat": 37.7793,
        "lon": -122.4193,
        "original_index": 0,
        "side_of_street": "right",
        "type": "break"
      },
      {
        "lat": 37.7817,
        "lon": -122.4108,
        "original_index": 1,
        "side_of_street": "right",
        "type": "break"
      },
      {
        "lat": 37.7844,
        "lon": -122.4079,
        "original_index": 2,
        "side_of_street": "right",
        "type": "break"
      }
    ],
    "status": 0,
    "status_message": "Found route between points",
    "summary": {
      "cost": 424.537,
      "has_ferry": false,
      "has_highway": false,
      "has_time_restrictions": true,
      "has_toll": false,
      "length": 1.548,
      "max_lat": 37.784135,
      "max_lon": -122.40748,
      "min_lat": 37.779214,
      "min_lon": -122.420355,
      "time": 201.05
    },
    "units": "kilometers"
  }
}

See the Routing Platform overview for API access, travel modes, and the machine-readable schema.

Reference: Valhalla optimized route API reference