Skip to content
Documentation

Trace attributes

Available on the following API tiers:

Transitland v2Beta

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

filters
object
Include or exclude specific attribute keys from the response. If omitted, all attributes are returned.
action
string
Enumincludeexclude

Exampleexclude

attributes
array: string
Attribute keys to include or exclude. Supports edge., node., matched., shape_attributes., and top-level keys such as shape, osm_changeset, and admin.*.
elevation_interval
number
Elevation sample interval in meters along the matched path. 0 = disabled.
Default0
encoded_polyline
string
Polyline6-encoded trace shape. Mutually exclusive with shape.
shape
array: object
GPS trace points. Mutually exclusive with encoded_polyline.
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).
shape_format
string
Not all formats are supported by all endpoints, e.g. no_shape is not valid for isochrone.
Defaultpolyline6
Enumpolyline6polyline5geojsonno_shape

Examplepolyline6

shape_match
string
Defaultwalk_or_snap
Enummap_snapedge_walkwalk_or_snap

Examplewalk_or_snap

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 -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":[{"lat":37.7891,"lon":-122.4011},{"lat":37.7887,"lon":-122.4016},{"lat":37.7883,"lon":-122.4022},{"lat":37.7879,"lon":-122.4028}],"shape_match":"map_snap"}'

Response

admins
array: object
Countries and states the matched path passes through.
alternate_paths
array: object
Other plausible matches, when the trace was ambiguous.
confidence_score
number
How confident the matcher is, from 0 to 1.
edges
array: object
Edges the trace was matched onto, in order. Each carries the graph's own attribution — see the Valhalla map-matching reference for the full field list, which follows the tile build rather than this API.
matched_points
array: object
One entry per input point, describing how it was matched.
distance_along_edge
number
How far along that edge the point falls, from 0 to 1.
distance_from_trace_point
number
Distance in meters from the input point to the matched point.
edge_index
integer
Index into edges of the edge this point matched.
lat
number
Latitude of the matched point.
lon
number
Longitude of the matched point.
type
string
Whether the point was matched, interpolated between matches, or left unmatched.
Enummatchedinterpolatedunmatched
distance_along_edge
number
How far along that edge the point falls, from 0 to 1.
distance_from_trace_point
number
Distance in meters from the input point to the matched point.
edge_index
integer
Index into edges of the edge this point matched.
lat
number
Latitude of the matched point.
lon
number
Longitude of the matched point.
type
string
Whether the point was matched, interpolated between matches, or left unmatched.
Enummatchedinterpolatedunmatched
osm_changeset
integer
OpenStreetMap changeset the tiles were built from.
raw_score
number
Unnormalized matching score. Lower is a closer match.
shape
string
The matched path, as an encoded polyline.
units
string
Units the lengths are expressed in.
Enumkilometersmiles

Example response

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

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

Reference: Valhalla map matching API reference