Documentation

Trace attributes

Last updated October 13, 2026

Available onExplorerPay As You GoHobbyist/AcademicEnterprisePlans and pricing

Snap a sequence of GPS coordinates to the road network and get back attributes along the matched path, such as speed limits, road class, and surface type. To get a route with directions instead, use map matching.

POSThttps://transit.land/api/v2/routing/valhalla/trace_attributes

Match a sequence of coordinates to the road network and return attributes along the matched path, such as speed limits, road class, and surface type.

Request

Top

filtersoptional object

Include or exclude specific attribute keys from the response. If omitted, all attributes are returned.

filters.actionoptional string: Example:exclude
Values
include Include only the listed Onestop IDs; everything else is excluded.
exclude Exclude all listed Onestop IDs; everything else is included.
filters.attributesoptional array of strings: Attribute keys to include or exclude. Supports edge., node., matched., shape_attributes., and top-level keys such as shape, osm_changeset, and admin.*.

Values
`include`	Include only the listed Onestop IDs; everything else is excluded.
`exclude`	Exclude all listed Onestop IDs; everything else is included.

elevation_intervaloptional number

Elevation sample interval in meters along the matched path. 0 = disabled.

Default:0

encoded_polylineoptional string

Polyline6-encoded trace shape. Mutually exclusive with shape.

shapeoptional array of objects

GPS trace points. Mutually exclusive with encoded_polyline.

shape.date_timeoptional string: Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
shape.display_latoptional 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.
shape.display_lonoptional 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.
shape.headingoptional integer: Preferred approach heading in degrees.
shape.heading_toleranceoptional 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).
shape.latnumberrequired
shape.lonnumberrequired
shape.minimum_reachabilityoptional 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).
Default:50
shape.nameoptional string: Label echoed in the response.
shape.node_snap_toleranceoptional number: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
shape.preferred_layeroptional 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.
shape.preferred_sideoptional string: Preferred side of road to snap to.
Default:eitherAllowed:same, opposite, eitherExample:opposite
shape.radiusoptional 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).
shape.rank_candidatesoptional boolean: Rank snap candidates by distance to input.
Default:true
shape.search_cutoffoptional integer: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
shape.search_filteroptional object: Optional filters to exclude candidate edges based on their attribution.
shape.streetoptional string: Street address hint for snapping.
shape.street_side_cutoffoptional string: Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_otherExample:primary
shape.street_side_max_distanceoptional 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).
shape.street_side_toleranceoptional 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).
shape.typeoptional string: First and last location are always forced to break.
Default:breakExample:break
Values
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.
shape.waitingoptional number: Waiting time in seconds at this stop (break/break_through only, not origin/destination).

Values
`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.

shape_formatoptional string

Not all formats are supported by all endpoints, e.g. no_shape is not valid for isochrone.

Default:polyline6Allowed:polyline6, polyline5, geojson, no_shapeExample:polyline6

shape_matchoptional string

Default:walk_or_snapExample:walk_or_snap

Values
`map_snap`	Map-matching algorithm for shapes that may not closely follow Valhalla edges, e.g. GPS traces. More expensive.
`edge_walk`	Exact edge-walking algorithm. Only use when the shape comes from a prior Valhalla route.
`walk_or_snap`	Try edge walking first; fall back to map snapping if it fails (default).

costingstringrequired

multimodal is not available. The street graph has no transit; use transit routing at /api/v2/routing/otp/plan.

Allowed:auto, bicycle, pedestrian, truck, bus, taxi, motor_scooter, motorcycle, bikeshare, auto_pedestrianExample:auto

costing_optionsoptional object

Costing options keyed by costing model name.

costing_options.autooptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.bicycleoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.bikeshareoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.busoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.motor_scooteroptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.motorcycleoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.pedestrianoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.taxioptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.truckoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.

date_timeoptional object

date_time.typeoptional integer: 0=current, 1=depart_at, 2=arrive_by, 3=invariant
Allowed:0, 1, 2, 3
date_time.valueoptional 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_locationsoptional array of objects

A set of locations to exclude or avoid within a route.

exclude_locations.date_timeoptional string: Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
exclude_locations.display_latoptional 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.
exclude_locations.display_lonoptional 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.
exclude_locations.headingoptional integer: Preferred approach heading in degrees.
exclude_locations.heading_toleranceoptional 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).
exclude_locations.latnumberrequired
exclude_locations.lonnumberrequired
exclude_locations.minimum_reachabilityoptional 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).
Default:50
exclude_locations.nameoptional string: Label echoed in the response.
exclude_locations.node_snap_toleranceoptional number: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
exclude_locations.preferred_layeroptional 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.
exclude_locations.preferred_sideoptional string: Preferred side of road to snap to.
Default:eitherAllowed:same, opposite, eitherExample:opposite
exclude_locations.radiusoptional 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).
exclude_locations.rank_candidatesoptional boolean: Rank snap candidates by distance to input.
Default:true
exclude_locations.search_cutoffoptional integer: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
exclude_locations.search_filteroptional object: Optional filters to exclude candidate edges based on their attribution.
exclude_locations.streetoptional string: Street address hint for snapping.
exclude_locations.street_side_cutoffoptional string: Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_otherExample:primary
exclude_locations.street_side_max_distanceoptional 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).
exclude_locations.street_side_toleranceoptional 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).
exclude_locations.typeoptional string: First and last location are always forced to break.
Default:breakExample:break
Values
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.
exclude_locations.waitingoptional number: Waiting time in seconds at this stop (break/break_through only, not origin/destination).

Values
`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.

exclude_polygonsoptional 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.

array of arraysarray of arrays: Array of closed coordinate rings. All edges intersecting any ring are excluded.
objectobject: GeoJSON FeatureCollection. Each Feature may carry a properties.levels array to restrict exclusion to specific building/indoor levels in pedestrian routing.

formatoptional string

Not all formats are supported by all endpoints, e.g. geotiff is isochrone-only.

Default:jsonAllowed:json, gpx, osrm, pbf, geotiff, mvtExample:json

idoptional string

Arbitrary request identifier echoed in the response.

languageoptional string

BCP47 locale for narrative output. See locales/ for supported values.

Default:en-US

linear_cost_factorsoptional array of objects

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.

object with shape, factorobject
object with type, geometry, propertiesobject

unitsoptional string

Default:kmAllowed:km, miles, mi

Response

Top

adminsarray of objects

Countries and states the matched path passes through. Each field is absent when unknown.

admins.country_codestring: ISO 3166-1 alpha-2 country code.
Example:US
admins.country_textstring: Country name.
Example:United States
admins.state_codestring: ISO 3166-2 subdivision code, without the country prefix.
Example:CA
admins.state_textstring: State or province name.
Example:California

alternate_pathsarray of objects

Other plausible matches. Always present, and empty when the trace matched one way only. Each holds the same path fields as the response itself: osm_changeset, shape, confidence_score, raw_score, admins, edges, elevation_interval, elevation, matched_points, and shape_attributes.

alternate_paths.adminsarray of objects

Countries and states the path passes through.

alternate_paths.confidence_scorenumber

How confident the matcher is, from 0 to 1.

alternate_paths.edgesarray of objects

Edges of this match, in order.

alternate_paths.edges.begin_headinginteger

Compass bearing at the start of the edge, in degrees.

alternate_paths.edges.begin_shape_indexinteger

Index into shape where the edge starts.

alternate_paths.edges.bicycle_networkinteger

Signed bicycle networks, as a bit mask. 1 national, 2 regional, 4 local, 8 mountain.

alternate_paths.edges.bicycle_typestring

Bicycle type, for bicycle edges.

Allowed:road, cross, hybrid, mountain

alternate_paths.edges.bridgeboolean

Whether the edge is a bridge.

alternate_paths.edges.country_crossingboolean

Whether the edge crosses a country border.

alternate_paths.edges.curvatureinteger

Curvature, from 0 for straight to 15. Off by default.

alternate_paths.edges.cycle_lanestring

Cycle lane on the edge.

Allowed:none, shared, dedicated, separated

alternate_paths.edges.densityinteger

Road density around the edge, from 0 to 15.

alternate_paths.edges.drive_on_rightboolean

Whether traffic drives on the right.

alternate_paths.edges.end_headinginteger

Compass bearing at the end of the edge, in degrees.

alternate_paths.edges.end_nodeobject

The node at the end of an edge.

alternate_paths.edges.end_node.admin_indexinteger

Index into admins of the area the node is in.

alternate_paths.edges.end_node.elapsed_costnumber

Cost from the start of the path to the node.

alternate_paths.edges.end_node.elapsed_timenumber

Time from the start of the path to the node, in seconds.

alternate_paths.edges.end_node.forkboolean

Whether the node is a fork in the road.

alternate_paths.edges.end_node.intersecting_edgesarray of objects

Other edges meeting at the node. Absent when there are none.

alternate_paths.edges.end_node.node_idinteger (int64)

OpenStreetMap node. Present only when the tiles were built with node identifiers.

alternate_paths.edges.end_node.time_zonestring

IANA time zone at the node. Absent when unknown.

alternate_paths.edges.end_node.traffic_signalboolean

Whether the node has a traffic signal.

alternate_paths.edges.end_node.transition_timenumber

Time spent passing through the node, as for a turn, in seconds.

alternate_paths.edges.end_node.typestring

What the node is.

Allowed:street_intersection, gate, bollard, toll_booth, transit_egress, transit_station, multi_use_transit_platform, bike_share, parking, motor_way_junction, border_control, toll_gantry, sump_buster, building_entrance, elevator

alternate_paths.edges.end_shape_indexinteger

Index into shape where the edge ends.

alternate_paths.edges.forwardboolean

Whether the path runs in the direction of the edge's shape.

alternate_paths.edges.hov_typestring

Occupancy requirement, meaningful only on HOV-only edges. Off by default; once requested it is on every edge, and ordinary roads read HOV-2.

Allowed:HOV-2, HOV-3

alternate_paths.edges.idinteger (int64)

Graph edge identifier.

alternate_paths.edges.internal_intersectionboolean

Whether the edge is internal to an intersection.

alternate_paths.edges.lane_connectivityarray of objects

Which lanes on the incoming way lead to which lanes on this edge. Present only when the data has lane connectivity.

alternate_paths.edges.lane_countinteger

Number of lanes in the direction of travel.

alternate_paths.edges.lengthnumber

Length of the traversed part of the edge, in the response's units.

alternate_paths.edges.levelsarray of arrays

Building levels the edge spans, as [from, to] pairs. Present only where the data has levels.

alternate_paths.edges.max_downward_gradeinteger

Steepest downward slope, in degrees. -500 when the tiles have no elevation data.

alternate_paths.edges.max_upward_gradeinteger

Steepest upward slope, in degrees. -500 when the tiles have no elevation data.

alternate_paths.edges.mean_elevationinteger

Mean elevation in meters, or feet when units is miles. Absent when the tiles have no elevation data.

alternate_paths.edges.namesarray of strings

Street names and route numbers. Absent when the edge has none.

alternate_paths.edges.node_idinteger (int64)

OpenStreetMap node the edge starts at. Present only when the tiles were built with node identifiers.

alternate_paths.edges.pedestrian_typestring

Traveler type, for pedestrian edges.

Allowed:foot, wheelchair

alternate_paths.edges.road_classstring

Road class.

Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_other

alternate_paths.edges.roundaboutboolean

Whether the edge is part of a roundabout.

alternate_paths.edges.sac_scaleinteger

Hiking difficulty, from 0 for none to 6 for difficult alpine hiking.

alternate_paths.edges.shoulderboolean

Whether the edge has a shoulder.

alternate_paths.edges.sidewalkstring

Which sides of the edge have a sidewalk.

Allowed:none, left, right, both

alternate_paths.edges.signobject

Guide-sign text on the edge. Present only where the edge has signs, and each list only when the sign carries it.

alternate_paths.edges.source_percent_alongnumber

Where the path enters the edge, from 0 to 1. Present only when not 0.

alternate_paths.edges.speedinteger

Speed the router used for the edge.

alternate_paths.edges.speed_limitinteger or string

Posted speed limit, or unlimited. Absent when unknown. Takes one of the 2 forms listed below.

alternate_paths.edges.speed_typestring

Whether the speed came from a tagged maxspeed or was assigned by road class.

Allowed:tagged, classified

alternate_paths.edges.speeds_fadedobject

The speed from each traffic source. speeds_non_faded is the source's own value; speeds_faded blends live traffic into the historical speed with distance from the start of the route, and appears only when the request's date_time is the current time. Each source is absent when the edge has none, except no_flow.

alternate_paths.edges.speeds_non_fadedobject

alternate_paths.edges.surfacestring

Road surface, from smoothest to roughest.

Allowed:paved_smooth, paved, paved_rough, compacted, dirt, gravel, path, impassable

alternate_paths.edges.target_percent_alongnumber

Where the path leaves the edge, from 0 to 1. Present only when not 1.

alternate_paths.edges.tollboolean

Whether the edge is a toll road.

alternate_paths.edges.traffic_segmentsarray of objects

Traffic segments the edge belongs to. Present only when traffic segment data is loaded.

alternate_paths.edges.traffic_signalboolean

Whether there is a traffic signal on the edge.

alternate_paths.edges.travel_modestring

Mode of travel on the edge.

Allowed:drive, pedestrian, bicycle

alternate_paths.edges.traversabilitystring

Which directions the edge can be traveled in by the request's mode.

Allowed:none, forward, backward, both

alternate_paths.edges.truck_routeboolean

Whether the edge is a designated truck route.

alternate_paths.edges.truck_speedinteger

Truck speed. Absent when the edge has none.

alternate_paths.edges.tunnelboolean

Whether the edge is a tunnel.

alternate_paths.edges.unpavedboolean

Whether the edge is unpaved.

alternate_paths.edges.usestring

What the edge is used for.

Allowed:road, ramp, turn_channel, track, driveway, alley, parking_aisle, emergency_access, drive_through, culdesac, living_street, service_road, cycleway, mountain_bike, sidewalk, footway, elevator, steps, escalator, path, pedestrian, platform, bridleway, pedestrian_crossing, rest_area, service_area, other, rail-ferry, ferry, rail, bus, egress_connection, platform_connection, transit_connection, construction

alternate_paths.edges.vehicle_typestring

Vehicle type, for drive edges: car, motorcycle, bus, or truck. Motor scooter costing returns the string null.

alternate_paths.edges.way_idinteger (int64)

OpenStreetMap way the edge was built from.

alternate_paths.edges.weighted_gradenumber

Grade in percent, weighted toward steeper sections.

alternate_paths.elevationarray of numbers

Elevation along the path.

alternate_paths.elevation_intervalnumber

Spacing of the elevation samples.

alternate_paths.matched_pointsarray of objects

One entry per input point.

alternate_paths.osm_changesetinteger (int64)

OpenStreetMap changeset the tiles were built from.

alternate_paths.raw_scorenumber

Unnormalized matching score. Lower is a closer match.

alternate_paths.shapestring

The matched path, as an encoded polyline.

alternate_paths.shape_attributesobject

Values for each segment between consecutive points of shape. Off by default: each list appears only when its shape_attributes.* filter is requested.

confidence_scorenumber

How confident the matcher is, from 0 to 1.

edgesarray of objects

Edges the trace was matched onto, in order.

edges.begin_headinginteger

Compass bearing at the start of the edge, in degrees.

edges.begin_shape_indexinteger

Index into shape where the edge starts.

edges.bicycle_networkinteger

Signed bicycle networks, as a bit mask. 1 national, 2 regional, 4 local, 8 mountain.

edges.bicycle_typestring

Bicycle type, for bicycle edges.

Allowed:road, cross, hybrid, mountain

edges.bridgeboolean

Whether the edge is a bridge.

edges.country_crossingboolean

Whether the edge crosses a country border.

edges.curvatureinteger

Curvature, from 0 for straight to 15. Off by default.

edges.cycle_lanestring

Cycle lane on the edge.

Allowed:none, shared, dedicated, separated

edges.densityinteger

Road density around the edge, from 0 to 15.

edges.drive_on_rightboolean

Whether traffic drives on the right.

edges.end_headinginteger

Compass bearing at the end of the edge, in degrees.

edges.end_nodeobject

The node at the end of an edge.

edges.end_node.admin_indexinteger

Index into admins of the area the node is in.

edges.end_node.elapsed_costnumber

Cost from the start of the path to the node.

edges.end_node.elapsed_timenumber

Time from the start of the path to the node, in seconds.

edges.end_node.forkboolean

Whether the node is a fork in the road.

edges.end_node.intersecting_edgesarray of objects

Other edges meeting at the node. Absent when there are none.

edges.end_node.node_idinteger (int64)

OpenStreetMap node. Present only when the tiles were built with node identifiers.

edges.end_node.time_zonestring

IANA time zone at the node. Absent when unknown.

edges.end_node.traffic_signalboolean

Whether the node has a traffic signal.

edges.end_node.transition_timenumber

Time spent passing through the node, as for a turn, in seconds.

edges.end_node.typestring

What the node is.

edges.end_shape_indexinteger

Index into shape where the edge ends.

edges.forwardboolean

Whether the path runs in the direction of the edge's shape.

edges.hov_typestring

Occupancy requirement, meaningful only on HOV-only edges. Off by default; once requested it is on every edge, and ordinary roads read HOV-2.

Allowed:HOV-2, HOV-3

edges.idinteger (int64)

Graph edge identifier.

edges.internal_intersectionboolean

Whether the edge is internal to an intersection.

edges.lane_connectivityarray of objects

Which lanes on the incoming way lead to which lanes on this edge. Present only when the data has lane connectivity.

edges.lane_countinteger

Number of lanes in the direction of travel.

edges.lengthnumber

Length of the traversed part of the edge, in the response's units.

edges.levelsarray of arrays

Building levels the edge spans, as [from, to] pairs. Present only where the data has levels.

edges.max_downward_gradeinteger

Steepest downward slope, in degrees. -500 when the tiles have no elevation data.

edges.max_upward_gradeinteger

Steepest upward slope, in degrees. -500 when the tiles have no elevation data.

edges.mean_elevationinteger

Mean elevation in meters, or feet when units is miles. Absent when the tiles have no elevation data.

edges.namesarray of strings

Street names and route numbers. Absent when the edge has none.

edges.node_idinteger (int64)

OpenStreetMap node the edge starts at. Present only when the tiles were built with node identifiers.

edges.pedestrian_typestring

Traveler type, for pedestrian edges.

Allowed:foot, wheelchair

edges.road_classstring

Road class.

Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_other

edges.roundaboutboolean

Whether the edge is part of a roundabout.

edges.sac_scaleinteger

Hiking difficulty, from 0 for none to 6 for difficult alpine hiking.

edges.shoulderboolean

Whether the edge has a shoulder.

edges.sidewalkstring

Which sides of the edge have a sidewalk.

Allowed:none, left, right, both

edges.signobject

Guide-sign text on the edge. Present only where the edge has signs, and each list only when the sign carries it.

edges.source_percent_alongnumber

Where the path enters the edge, from 0 to 1. Present only when not 0.

edges.speedinteger

Speed the router used for the edge.

edges.speed_limitinteger or string

Posted speed limit, or unlimited. Absent when unknown. Takes one of the 2 forms listed below.

edges.speed_typestring

Whether the speed came from a tagged maxspeed or was assigned by road class.

Allowed:tagged, classified

edges.speeds_fadedobject

edges.speeds_non_fadedobject

edges.surfacestring

Road surface, from smoothest to roughest.

Allowed:paved_smooth, paved, paved_rough, compacted, dirt, gravel, path, impassable

edges.target_percent_alongnumber

Where the path leaves the edge, from 0 to 1. Present only when not 1.

edges.tollboolean

Whether the edge is a toll road.

edges.traffic_segmentsarray of objects

Traffic segments the edge belongs to. Present only when traffic segment data is loaded.

edges.traffic_signalboolean

Whether there is a traffic signal on the edge.

edges.travel_modestring

Mode of travel on the edge.

Allowed:drive, pedestrian, bicycle

edges.traversabilitystring

Which directions the edge can be traveled in by the request's mode.

Allowed:none, forward, backward, both

edges.truck_routeboolean

Whether the edge is a designated truck route.

edges.truck_speedinteger

Truck speed. Absent when the edge has none.

edges.tunnelboolean

Whether the edge is a tunnel.

edges.unpavedboolean

Whether the edge is unpaved.

edges.usestring

What the edge is used for.

edges.vehicle_typestring

Vehicle type, for drive edges: car, motorcycle, bus, or truck. Motor scooter costing returns the string null.

edges.way_idinteger (int64)

OpenStreetMap way the edge was built from.

edges.weighted_gradenumber

Grade in percent, weighted toward steeper sections.

elevationarray of numbers

Elevation along the path, sampled every elevation_interval. Present with elevation_interval.

elevation_intervalnumber

Spacing of the elevation samples, in meters, or feet when units is miles. Present when the request sets elevation_interval.

idstring

The request's id, echoed back. Absent when the request has none.

matched_pointsarray of objects

One entry per input point, describing how it was matched.

matched_points.begin_route_discontinuityboolean: Whether the path breaks before this point, as when the trace jumps. Present only when true.
matched_points.distance_along_edgenumber: How far along that edge the point falls, from 0 to 1. Absent for unmatched points.
matched_points.distance_from_trace_pointnumber: Distance in meters from the input point to the matched point. Absent for unmatched points.
matched_points.edge_indexinteger: Index into edges of the edge this point matched. Absent for unmatched points.
matched_points.end_route_discontinuityboolean: Whether the path breaks after this point. Present only when true.
matched_points.latnumber (double): Latitude of the matched point.
matched_points.lonnumber (double): Longitude of the matched point.
matched_points.typestring: Whether the point was matched, interpolated between matches, or left unmatched.
Allowed:matched, interpolated, unmatched

osm_changesetinteger (int64)

OpenStreetMap changeset the tiles were built from.

raw_scorenumber

Unnormalized matching score. Lower is a closer match.

shapestring

The matched path, as an encoded polyline.

shape_attributesobject

Values for each segment between consecutive points of shape. Off by default: each list appears only when its shape_attributes.* filter is requested.

shape_attributes.closurearray of objects

Stretches of shape closed to traffic.

shape_attributes.congestionarray of numbers

Congestion on each segment, from live traffic.

shape_attributes.lengtharray of numbers

Length of each segment, in kilometers.

shape_attributes.speedarray of numbers

Speed on each segment, in km/h.

shape_attributes.speed_limitarray of numbers

Posted speed limit on each segment, in km/h.

shape_attributes.timearray of numbers

Time to travel each segment, in seconds.

unitsstring

Units the lengths, speeds, and elevations are expressed in.

Allowed:kilometers, miles

warningsarray of objects

Non-fatal notes about the request. Absent when there are none.

warnings.codeinteger: Valhalla warning code.
warnings.textstring: Human-readable warning.

curl -X POST "https://transit.land/api/v2/routing/valhalla/trace_attributes" \
  -H "apikey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"costing":"auto","shape_match":"map_snap","shape":[{"lat":37.7891,"lon":-122.4011},{"lat":37.7887,"lon":-122.4016},{"lat":37.7883,"lon":-122.4022},{"lat":37.7879,"lon":-122.4028}]}'

Example responseShowing 2 of 3 edges, Showing 2 of 4 matched_points

{
  "units": "kilometers",
  "osm_changeset": 190996078,
  "shape": "shmagAtbwmhFnA`BbAxAjQnV",
  "confidence_score": 1,
  "raw_score": 200000096,
  "admins": [
    {
      "country_code": "US",
      "country_text": "United States",
      "state_code": "CA",
      "state_text": "California"
    }
  ],
  "edges": [
    {
      "truck_route": false,
      "density": 13,
      "sac_scale": 0,
      "shoulder": false,
      "sidewalk": "none",
      "bicycle_network": 0,
      "cycle_lane": "none",
      "lane_count": 1,
      "max_downward_grade": 0,
      "max_upward_grade": 0,
      "weighted_grade": 0,
      "mean_elevation": 8,
      "way_id": 47172320,
      "id": 3857389836850,
      "travel_mode": "drive",
      "vehicle_type": "car",
      "surface": "paved_smooth",
      "drive_on_right": true,
      "internal_intersection": false,
      "roundabout": false,
      "bridge": false,
      "tunnel": false,
      "unpaved": false,
      "toll": false,
      "use": "road",
      "traversability": "both",
      "end_shape_index": 1,
      "begin_shape_index": 0,
      "end_heading": 224,
      "begin_heading": 224,
      "road_class": "residential",
      "speed": 30,
      "speed_type": "classified",
      "speeds_non_faded": {
        "no_flow": 30
      },
      "country_crossing": false,
      "forward": true,
      "traffic_signal": false,
      "length": 0.006,
      "names": [
        "Stevenson Street"
      ],
      "end_node": {
        "intersecting_edges": [
          {
            "cyclability": "backward",
            "from_edge_name_consistency": false,
            "to_edge_name_consistency": false,
            "begin_heading": 315,
            "use": "cycleway",
            "road_class": "service_other"
          },
          {
            "cyclability": "forward",
            "from_edge_name_consistency": false,
            "to_edge_name_consistency": false,
            "begin_heading": 137,
            "use": "cycleway",
            "road_class": "service_other"
          }
        ],
        "elapsed_time": 0.72,
        "elapsed_cost": 0.846,
        "admin_index": 0,
        "type": "street_intersection",
        "traffic_signal": false,
        "fork": false,
        "transition_time": 0.008
      }
    },
    {
      "truck_route": false,
      "density": 13,
      "sac_scale": 0,
      "shoulder": false,
      "sidewalk": "none",
      "bicycle_network": 0,
      "cycle_lane": "none",
      "lane_count": 1,
      "max_downward_grade": 0,
      "max_upward_grade": 0,
      "weighted_grade": 0,
      "mean_elevation": 8,
      "way_id": 47172320,
      "id": 3930773379634,
      "travel_mode": "drive",
      "vehicle_type": "car",
      "surface": "paved_smooth",
      "drive_on_right": true,
      "internal_intersection": false,
      "roundabout": false,
      "bridge": false,
      "tunnel": false,
      "unpaved": false,
      "toll": false,
      "use": "road",
      "traversability": "both",
      "end_shape_index": 2,
      "begin_shape_index": 1,
      "end_heading": 226,
      "begin_heading": 226,
      "road_class": "residential",
      "speed": 30,
      "speed_type": "classified",
      "speeds_non_faded": {
        "no_flow": 30
      },
      "country_crossing": false,
      "forward": true,
      "traffic_signal": false,
      "length": 0.005,
      "names": [
        "Stevenson Street"
      ],
      "end_node": {
        "intersecting_edges": [
          {
            "walkability": "both",
            "from_edge_name_consistency": false,
            "to_edge_name_consistency": false,
            "begin_heading": 315,
            "use": "pedestrian_crossing",
            "road_class": "service_other"
          },
          {
            "walkability": "both",
            "from_edge_name_consistency": false,
            "to_edge_name_consistency": false,
            "begin_heading": 125,
            "use": "pedestrian_crossing",
            "road_class": "service_other"
          }
        ],
        "elapsed_time": 1.328,
        "elapsed_cost": 1.551,
        "admin_index": 0,
        "type": "street_intersection",
        "traffic_signal": false,
        "fork": false,
        "transition_time": 0.019
      }
    }
  ],
  "matched_points": [
    {
      "lon": -122.400826,
      "lat": 37.788826,
      "type": "matched",
      "edge_index": 0,
      "distance_along_edge": 0,
      "distance_from_trace_point": 38.559444
    },
    {
      "lon": -122.401297,
      "lat": 37.788458,
      "type": "matched",
      "edge_index": 2,
      "distance_along_edge": 0.701669,
      "distance_from_trace_point": 37.635989
    }
  ],
  "alternate_paths": []
}

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

Reference: Valhalla map matching API reference