openapi: 3.1.0
info:
title: Valhalla Routing Expansion Trace Route API
version: 3.x
description: 'Open-source routing engine for OpenStreetMap data.
All POST endpoints accept JSON (some also protobuf with `Content-Type: application/x-protobuf`).
'
license:
name: MIT
url: https://github.com/valhalla/valhalla/blob/master/COPYING
servers:
- url: https://valhalla1.openstreetmap.de
security: []
tags:
- name: Trace Route
paths:
/trace_route:
post:
operationId: traceRoute
summary: /trace_route
description: Map-matched turn-by-turn route
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TraceRouteRequest'
responses:
'200':
description: Map-matched route result
content:
application/json:
examples:
default:
externalValue: ./examples/trace_route.json
'400':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/RateLimited'
tags:
- Trace Route
components:
responses:
RateLimited:
description: 'Rate limit exceeded. The public service enforces a per-user limit of
1 request per second and a global limit of 100 requests per second.
The body is nginx''s default 429 HTML page.
'
content:
text/html:
schema:
type: string
Error:
description: Request error
content:
application/json:
schema:
type: object
properties:
error_code:
type: integer
error:
type: string
status_code:
type: integer
status:
type: string
schemas:
OutputFormat:
type: string
enum:
- json
- gpx
- osrm
- pbf
- geotiff
- mvt
default: json
description: Not all formats are supported by all endpoints, e.g. `geotiff` is isochrone-only.
example: json
CostingOptions:
type: object
description: Costing options keyed by costing model name.
properties:
auto:
$ref: '#/components/schemas/AutoCostingOptions'
bus:
$ref: '#/components/schemas/AutoCostingOptions'
taxi:
$ref: '#/components/schemas/AutoCostingOptions'
bicycle:
$ref: '#/components/schemas/BicycleCostingOptions'
pedestrian:
$ref: '#/components/schemas/PedestrianCostingOptions'
bikeshare:
$ref: '#/components/schemas/PedestrianCostingOptions'
truck:
$ref: '#/components/schemas/TruckCostingOptions'
motorcycle:
$ref: '#/components/schemas/MotorcycleCostingOptions'
motor_scooter:
$ref: '#/components/schemas/MotorScooterCostingOptions'
multimodal:
$ref: '#/components/schemas/TransitCostingOptions'
transit:
$ref: '#/components/schemas/TransitCostingOptions'
Location:
type: object
required:
- lat
- lon
properties:
lat:
type: number
minimum: -90
maximum: 90
lon:
type: number
minimum: -180
maximum: 180
type:
type: string
enum:
- break
- through
- via
- break_through
example: break
default: break
description: First and last location are always forced to `break`.
x-enumDescriptions:
break: Stop here; starts or ends a route leg. Allows U-turns.
through: Pass through without stopping. No U-turn; keeps direction of travel.
via: Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_through: Like `break` but does not allow U-turns at the location.
name:
type: string
description: Label echoed in the response.
street:
type: string
description: Street address hint for snapping.
date_time:
type: string
description: Per-location ISO 8601 datetime override, in the format `YYYY-MM-DDTHH:MM`, e.g. `2016-07-03T08:06`.
heading:
type: integer
minimum: 0
maximum: 360
description: Preferred approach heading in degrees.
heading_tolerance:
type: integer
x-rad-min: 0
x-rad-max: 180
x-rad-default: 60
description: '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).
'
preferred_layer:
type: integer
x-rad-min: -1
x-rad-max: 5
description: '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.
'
node_snap_tolerance:
type: number
minimum: 0
x-rad-max: 100
x-rad-default: 5
description: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
minimum_reachability:
type: integer
minimum: 0
x-rad-max: 250
default: 50
description: Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
radius:
type: integer
minimum: 0
x-rad-max: 200
x-rad-default: 0
description: '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).
'
search_cutoff:
type: integer
minimum: 0
x-rad-min: 10000
x-rad-max: 100000
x-rad-default: 35000
description: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
rank_candidates:
type: boolean
default: true
description: Rank snap candidates by distance to input.
preferred_side:
type: string
default: either
example: opposite
enum:
- same
- opposite
- either
description: Preferred side of road to snap to.
display_lat:
type: number
minimum: -90
maximum: 90
description: '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:
type: number
minimum: -180
maximum: 180
description: '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.
'
street_side_tolerance:
type: integer
minimum: 0
x-rad-max: 50
x-rad-default: 5
description: '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).
'
street_side_max_distance:
type: integer
minimum: 0
x-rad-max: 10000
x-rad-default: 1000
description: '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_cutoff:
default: service_other
$ref: '#/components/schemas/RoadClass'
description: Ignore side preference for roads above this class.
waiting:
type: number
minimum: 0
x-rad-max: 10000
description: Waiting time in seconds at this stop (break/break_through only, not origin/destination).
search_filter:
$ref: '#/components/schemas/SearchFilter'
description: 'A set of optional filters to exclude candidate edges based on their attribution. Note that these are "hard" filters, i.e. it''s possible to end up with no location candidates if these filters are too restricted.
'
FilterAction:
type: string
enum:
- include
- exclude
example: exclude
x-enumDescriptions:
include: Include only the listed Onestop IDs; everything else is excluded.
exclude: Exclude all listed Onestop IDs; everything else is included.
TransitFilterOptions:
type: object
properties:
action:
allOf:
- $ref: '#/components/schemas/FilterAction'
- description: Whether to include only the listed Onestop IDs or exclude them.
ids:
type: array
description: 'List of Onestop IDs to filter. The OneStop ID is simply the feeds''s directory name and the object''s GTFS ID separated by an underscore, i.e. a route with `route_id: AUR` in `routes.txt` from the feed `NYC` would have the OneStop ID `NYC_AUR`, similar with operators/agencies.
'
items:
type: string
example: NYC_AUR
MotorcycleCostingOptions:
allOf:
- $ref: '#/components/schemas/BaseCostingOptions'
- type: object
description: Options for motorcycle costing. Parsed in src/sif/motorcyclecost.cc.
properties:
use_highways:
type: number
minimum: 0
maximum: 1
default: 0.5
description: 'This value indicates the willingness to take highways. This is a range of values between 0 and 1. Values near 0 attempt to avoid highways and values near 1 will favor highways. Note that sometimes highways are required to complete a route so values of 0 are not guaranteed to avoid highways entirely.
'
use_tolls:
type: number
minimum: 0
maximum: 1
default: 0.5
description: This value indicates the willingness to take roads with tolls. This is a range of values between 0 and 1. Values smaller than 0.5 attempt to avoid tolls and values greater than 0.5 will slightly favor them. The default value is 0.5, indicating no preference. Note that sometimes roads with tolls are required to complete a route so values of 0 are not guaranteed to avoid them entirely.
use_trails:
type: number
minimum: 0
maximum: 1
default: 0
description: 'A riders''s desire for adventure in their routes. This is a range of values from 0 to 1, where 0 will avoid trails, tracks, unclassified or bad surfaces and values towards 1 will tend to avoid major roads and route on secondary roads.
'
top_speed:
type: integer
minimum: 10
maximum: 252
default: 140
description: "Top speed the vehicle can go in km/h. Also used to avoid roads with higher speeds than this value. `top_speed` must be between 10 and 252 km/h. The default value is 140 km/h for motorcycle. \n"
MotorScooterCostingOptions:
allOf:
- $ref: '#/components/schemas/BaseCostingOptions'
- type: object
description: Options for motor_scooter costing. Parsed in src/sif/motorscootercost.cc.
properties:
top_speed:
type: integer
minimum: 20
maximum: 252
default: 45
description: "Top speed the vehicle can go in km/h. Also used to avoid roads with higher speeds than this value. `top_speed` must be between 10 and 252 km/h. The default value is 45 km/h for motor_scooter. \n"
use_hills:
type: number
minimum: 0
maximum: 1
default: 0.5
description: "A rider's desire to use hills in their routes. This is a range of values from 0 to 1, where 0 attempts to avoid hills and steep grades even if it means a longer (time and distance) path, while 1 indicates the rider does not fear hills and steeper grades. Based on the `use_hills` factor, penalties are applied to roads based on elevation change and grade. These penalties help the path avoid hilly roads in favor of flatter roads or less steep grades where available. Note that it is not always possible to find alternate paths to avoid hills (for example when route locations are in mountainous areas). \n"
use_primary:
type: number
minimum: 0
maximum: 1
default: 0.5
description: 'A rider''s propensity to use primary roads. This is a range of values from 0 to 1, where 0 attempts to avoid primary roads, and 1 indicates the rider is more comfortable riding on primary roads. Based on the `use_primary` factor, roads with certain classifications and higher speeds are penalized in an attempt to avoid them when finding the best path.
'
BicycleCostingOptions:
allOf:
- $ref: '#/components/schemas/BaseCostingOptions'
- type: object
description: Options for bicycle costing. Parsed in src/sif/bicyclecost.cc.
properties:
bicycle_type:
type: string
description: The type of bicycle. Affects the cycling speed and surface factors.
default: hybrid
enum:
- road
- hybrid
- city
- cross
- mountain
x-enumDescriptions:
road: A road-style bicycle with narrow tires that is generally lightweight and designed for speed on paved surfaces. Sets cycling_speed to 25 km/h.
hybrid: A bicycle made mostly for city riding or casual riding on roads and paths with good surfaces. Sets cycling_speed to 18 km/h.
city: A bicycle made mostly for city riding or casual riding on roads and paths with good surfaces. Sets cycling_speed to 18 km/h.
cross: A cyclo-cross bicycle, which is similar to a road bicycle but with wider tires suitable to rougher surfaces. Sets cycling_speed to 20 km/h.
mountain: A mountain bicycle suitable for most surfaces but generally heavier and slower on paved surfaces. Sets cycling_speed to 16 km/h.
cycling_speed:
type: number
minimum: 5
description: Cycling speed in km/h. Defaults depend on transport_type.
use_roads:
type: number
minimum: 0
maximum: 1
default: 0.25
description: 'A cyclist''s propensity to use roads alongside other vehicles. This is a range of values from 0 to 1, where 0 attempts to avoid roads and stay on cycleways and paths, and 1 indicates the rider is more comfortable riding on roads. Based on the `use_roads` factor, roads with certain classifications and higher speeds are penalized in an attempt to avoid them when finding the best path.
'
use_hills:
type: number
minimum: 0
maximum: 1
default: 0.25
description: "A cyclist's desire to tackle hills in their routes. This is a range of values from 0 to 1, where 0 attempts to avoid hills and steep grades even if it means a longer (time and distance) path, while 1 indicates the rider does not fear hills and steeper grades. Based on the `use_hills` factor, penalties are applied to roads based on elevation change and grade. These penalties help the path avoid hilly roads in favor of flatter roads or less steep grades where available. Note that it is not always possible to find alternate paths to avoid hills (for example when route locations are in mountainous areas). \n"
avoid_bad_surfaces:
type: number
minimum: 0
maximum: 1
default: 0.25
description: 'This value is meant to represent how much a cyclist wants to avoid roads with poor surfaces relative to the bicycle type being used. This is a range of values between 0 and 1. When the value is 0, there is no penalization of roads with different surface types; only bicycle speed on each surface is taken into account. As the value approaches 1, roads with poor surfaces for the bike are penalized heavier so that they are only taken if they significantly improve travel time. When the value is equal to 1, all bad surfaces are completely disallowed from routing, including start and end points.
'
bss_return_cost:
type: number
minimum: 0
maximum: 43200
default: 120
description: 'This value is useful when `bikeshare` is chosen as travel mode. It is meant to give the time will be used to return a rental bike. This value will be displayed in the final directions and used to calculate the whole duration.
'
bss_rent_penalty:
type: number
minimum: 0
maximum: 43200
default: 0
description: 'This value is useful when `bikeshare` is chosen as travel mode. It is meant to describe the potential effort to return a rental bike. This value won''t be displayed and used only inside of the algorithm.
'
BaseCostingOptions:
type: object
description: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
allOf:
- $ref: '#/components/schemas/HardExclusions'
- type: object
properties:
name:
type: string
description: Required for recostings entries; must be unique.
shortest:
type: boolean
default: false
description: '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.
'
disable_hierarchy_pruning:
type: boolean
default: false
description: "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 \n"
ignore_restrictions:
type: boolean
description: '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.
'
ignore_oneways:
type: boolean
default: false
description: '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.
'
ignore_access:
type: boolean
default: false
description: 'Will ignore mode-specific access tags. Especially useful for matching GPS traces to the road network regardless of restrictions
'
ignore_closures:
type: boolean
default: false
description: '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.
'
destination_only_penalty:
type: number
minimum: 0
maximum: 43200
default: 600
description: 'A penalty applied when entering an road which is only allowed to enter if necessary to reach the [destination](https://wiki.openstreetmap.org/wiki/Tag:vehicle%3Ddestination).
'
maneuver_penalty:
type: number
minimum: 0
maximum: 43200
default: 5
description: '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.
'
alley_penalty:
type: number
minimum: 0
maximum: 43200
description: A penalty that is applied when transitioning onto an alley. Default is 60 seconds for bicycle, 5 seconds otherwise.
gate_cost:
type: number
minimum: 0
maximum: 43200
default: 30
description: 'A cost applied when a [gate](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dgate) with undefined or private access is encountered. This cost is added to estimated and elapsed times.
'
gate_penalty:
type: number
minimum: 0
maximum: 43200
description: 'A penalty applied when a [gate](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dgate) with no access information is on the road. Default is 300 for bicycle, 30 otherwise.
'
private_access_penalty:
type: number
minimum: 0
maximum: 43200
description: 'A penalty applied when a [gate](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dgate) or [bollard](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dbollard) with `access=private` is encountered. Default is 600 for pedestrian, 450 otherwise.
'
country_crossing_cost:
type: number
minimum: 0
maximum: 43200
default: 600
description: A cost applied when encountering an international border. This cost is added to the estimated and elapsed times.
country_crossing_penalty:
type: number
minimum: 0
maximum: 43200
default: 0
description: 'A penalty applied for a country crossing. This penalty can be used to create paths that avoid spanning country boundaries.
'
ferry_cost:
type: number
minimum: 0
maximum: 43200
default: 300
description: A cost applied when entering a ferry. This cost is added to the estimated and elapsed times.
use_ferry:
type: number
minimum: 0
maximum: 1
default: 0.5
description: '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.
'
rail_ferry_cost:
type: number
minimum: 0
maximum: 43200
default: 300
description: A cost applied when entering a rail ferry. This cost is added to the estimated and elapsed times.
use_rail_ferry:
type: number
minimum: 0
maximum: 1
default: 0.4
description: '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.
'
toll_booth_cost:
type: number
minimum: 0
maximum: 43200
default: 15
description: 'A cost applied when a [toll booth](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dtoll_booth) is encountered. This cost is added to the estimated and elapsed times.
'
toll_booth_penalty:
type: number
minimum: 0
maximum: 43200
default: 0
description: 'A penalty applied to the cost when a [toll booth](https://wiki.openstreetmap.org/wiki/Tag:barrier%3Dtoll_booth) is encountered. This penalty can be used to create paths that avoid toll roads.
'
service_penalty:
type: number
minimum: 0
maximum: 43200
description: 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.
service_factor:
type: number
minimum: 0.1
maximum: 100000
default: 1.0
description: 'A factor that modifies (multiplies) the cost when generic service roads are encountered.
'
use_tracks:
type: number
minimum: 0
maximum: 1
description: '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.
'
use_living_streets:
type: number
minimum: 0
maximum: 1
description: '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.
'
closure_factor:
type: number
minimum: 1
maximum: 10
default: 9.0
description: '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.
'
speed_penalty_factor:
type: number
minimum: 0
maximum: 1
default: 0.05
description: '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.
'
fixed_speed:
type: integer
minimum: 0
maximum: 252
default: 0
description: '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.
'
speed_types:
type: array
items:
$ref: '#/components/schemas/SpeedType'
uniqueItems: true
minItems: 0
maxItems: 4
description: '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.
'
DateTimeOptions:
type: object
properties:
type:
type: integer
enum:
- 0
- 1
- 2
- 3
description: 0=current, 1=depart_at, 2=arrive_by, 3=invariant
value:
type: string
description: ISO 8601 local datetime string in the format `YYYY-MM-DDTHH:MM`, e.g. `2016-07-03T08:06`. Required for types 1, 2, 3.
ShapeMatch:
type: string
enum:
- map_snap
- edge_walk
- walk_or_snap
default: walk_or_snap
example: walk_or_snap
x-enumDescriptions:
edge_walk: Exact edge-walking algorithm. Only use when the shape comes from a prior Valhalla route.
map_snap: Map-matching algorithm for shapes that may not closely follow Valhalla edges, e.g. GPS traces. More expensive.
walk_or_snap: Try edge walking first; fall back to map snapping if it fails (default).
TraceRequest:
allOf:
- $ref: '#/components/schemas/BaseRequest'
- type: object
required:
- costing
properties:
shape:
type: array
minItems: 2
x-rad-max-items: 100
items:
$ref: '#/components/schemas/Location'
description: GPS trace points. Mutually exclusive with encoded_polyline.
encoded_polyline:
type: string
description: Polyline6-encoded trace shape. Mutually exclusive with shape.
shape_match:
$ref: '#/components/schemas/ShapeMatch'
shape_format:
$ref: '#/components/schemas/ShapeFormat'
elevation_interval:
type: number
minimum: 0
x-rad-max: 100
default: 0
description: Elevation sample interval in meters along the matched path. 0 = disabled.
LinearCostFactor:
description: 'Either an encoded-polyline form or a GeoJSON LineString feature. In case of passing GeoJSON, the factor must be passed as a feature property. Note that the geometry must align with shapes present in Valhalla''s graph.
'
oneOf:
- $ref: '#/components/schemas/ShapeFactorVariant'
- $ref: '#/components/schemas/GeoJsonFactorVariant'
BaseRequest:
type: object
properties:
id:
type: string
description: Arbitrary request identifier echoed in the response.
format:
$ref: '#/components/schemas/OutputFormat'
units:
type: string
enum:
- km
- miles
- mi
default: km
language:
type: string
default: en-US
description: BCP47 locale for narrative output. See locales/ for supported values.
costing:
$ref: '#/components/schemas/CostingType'
costing_options:
$ref: '#/components/schemas/CostingOptions'
date_time:
$ref: '#/components/schemas/DateTimeOptions'
exclude_locations:
type: array
items:
$ref: '#/components/schemas/Location'
description: A set of locations to exclude or avoid within a route.
exclude_polygons:
description: 'Array of coordinate rings `[[lon,lat],…]` or a GeoJSON FeatureCollection. Roads intersecting these rings will be avoided during path finding.
'
oneOf:
- type: array
description: Array of closed coordinate rings. All edges intersecting an
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/valhalla/refs/heads/main/openapi/valhalla-trace-route-api-openapi.yml