Skip to content
Documentation

Locate

Last updated

Report what the road network looks like near one or more coordinates: which edges a location would snap to, how far away they are, and what the graph knows about them. Useful for debugging routes.

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

Find the nearest road or path network locations for given coordinates. Useful for debugging routes.

Request

The request object, url-encoded. Identical to the POST body. Encode spaces as %20, or send the JSON without spaces. The API does not decode + as a space and rejects the request as unparseable.

locationsarray of objectsrequired
locations.date_timeoptional string
Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
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.
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.
locations.headingoptional integer
Preferred approach heading in degrees.
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).
locations.latnumberrequired
locations.lonnumberrequired
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

locations.nameoptional string
Label echoed in the response.
locations.node_snap_toleranceoptional number
Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
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.
locations.preferred_sideoptional string
Preferred side of road to snap to.

Default:eitherAllowed:same, opposite, eitherExample:opposite

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).
locations.rank_candidatesoptional boolean
Rank snap candidates by distance to input.

Default:true

locations.search_cutoffoptional integer
Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
locations.search_filteroptional object
Optional filters to exclude candidate edges based on their attribution.
locations.streetoptional string
Street address hint for snapping.
locations.street_side_cutoffoptional string

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

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).
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).
locations.typeoptional string
First and last location are always forced to break.

Default:breakExample:break

Values
breakStop here; starts or ends a route leg. Allows U-turns.
throughPass through without stopping. No U-turn; keeps direction of travel.
viaWaypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_throughLike `break` but does not allow U-turns at the location.
locations.waitingoptional number
Waiting time in seconds at this stop (break/break_through only, not origin/destination).
verboseoptional boolean
Return dense edge and node attribution. When false, only the closest point, way ID, and side of street are returned.

Default:false

costingoptional string
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
breakStop here; starts or ends a route leg. Allows U-turns.
throughPass through without stopping. No U-turn; keeps direction of travel.
viaWaypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_throughLike `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).
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

edgesnullable array of objects
Candidate edges the location could snap to, nearest first. Null when no data was found near the location.
edges.access_restrictionsarray of objects
Restrictions that apply to travel on the edge.
edges.bounding_circleobject
The search radius that found this edge.
edges.correlated_latnumber (double)
Latitude of the point on the edge the location snapped to.
edges.correlated_lonnumber (double)
Longitude of the point on the edge the location snapped to.
edges.distancenumber
Distance in meters from the requested point to the snapped point.
edges.edgeobject
The directed edge as stored in the routing graph.
edges.edge_idobject
A graph identifier: the hierarchy level, the tile within it, and the object's index in that tile, plus value, all three packed into one integer.
edges.edge_infoobject
Attributes shared by both directions of the edge.
edges.headingnumber
Compass bearing of the edge at the snapped point, in degrees.
edges.inbound_reachinteger
How many nodes can reach this edge, up to the search's limit. Low values mark disconnected islands.
edges.incidentsarray of objects
Traffic incidents on the edge, when incident data is loaded.
edges.linear_referencestring
OpenLR location reference for the edge, as a base64 string.
edges.live_speedobject
Live traffic on the edge, in km/h. Empty when the edge has no live traffic. The edge is split into up to three segments at the breakpoints, each with its own speed and congestion.
edges.outbound_reachinteger
How many nodes this edge can reach, up to the search's limit.
edges.percent_alongnumber
How far along the edge the snapped point falls, from 0 to 1.
edges.predicted_speedsarray of integers
Historical speed profile in km/h, one value per 5 minutes of the week starting Sunday 00:00 local time, so 2016 values. Empty when the edge has no profile.
edges.shoulderboolean
Whether the edge has a shoulder.
edges.side_of_streetstring
Which side of the edge the requested point lies on.

Allowed:left, right, neither

edges.timed_predicted_speedinteger
Historical speed in km/h at the location's date_time. Present when the location sets date_time and the edge has a speed profile.
edges.way_idinteger (int64)
OpenStreetMap way the edge was built from. Without verbose only.
filtered_edgesarray of objects
Candidate edges the request's search filters excluded. Absent when none were.
filtered_edges.access_restrictionsarray of objects
Restrictions that apply to travel on the edge.
filtered_edges.bounding_circleobject
The search radius that found this edge.
filtered_edges.correlated_latnumber (double)
Latitude of the point on the edge the location snapped to.
filtered_edges.correlated_lonnumber (double)
Longitude of the point on the edge the location snapped to.
filtered_edges.distancenumber
Distance in meters from the requested point to the snapped point.
filtered_edges.edgeobject
The directed edge as stored in the routing graph.
filtered_edges.edge_idobject
A graph identifier: the hierarchy level, the tile within it, and the object's index in that tile, plus value, all three packed into one integer.
filtered_edges.edge_infoobject
Attributes shared by both directions of the edge.
filtered_edges.headingnumber
Compass bearing of the edge at the snapped point, in degrees.
filtered_edges.inbound_reachinteger
How many nodes can reach this edge, up to the search's limit. Low values mark disconnected islands.
filtered_edges.incidentsarray of objects
Traffic incidents on the edge, when incident data is loaded.
filtered_edges.linear_referencestring
OpenLR location reference for the edge, as a base64 string.
filtered_edges.live_speedobject
Live traffic on the edge, in km/h. Empty when the edge has no live traffic. The edge is split into up to three segments at the breakpoints, each with its own speed and congestion.
filtered_edges.outbound_reachinteger
How many nodes this edge can reach, up to the search's limit.
filtered_edges.percent_alongnumber
How far along the edge the snapped point falls, from 0 to 1.
filtered_edges.predicted_speedsarray of integers
Historical speed profile in km/h, one value per 5 minutes of the week starting Sunday 00:00 local time, so 2016 values. Empty when the edge has no profile.
filtered_edges.shoulderboolean
Whether the edge has a shoulder.
filtered_edges.side_of_streetstring
Which side of the edge the requested point lies on.

Allowed:left, right, neither

filtered_edges.timed_predicted_speedinteger
Historical speed in km/h at the location's date_time. Present when the location sets date_time and the edge has a speed profile.
filtered_edges.way_idinteger (int64)
OpenStreetMap way the edge was built from. Without verbose only.
input_latnumber (double)
Latitude as requested.
input_lonnumber (double)
Longitude as requested.
nodesnullable array of objects
Nodes the location snaps to, when it falls at the end of an edge. Null when no data was found near the location.
nodes.accessobject
Which travelers may pass. Node access omits moped and motorcycle.
nodes.administrativeobject
Country, state, and time zone at the node.
nodes.densityinteger
Road density around the node, from 0 to 15.
nodes.drive_on_rightboolean
Whether traffic drives on the right.
nodes.edge_countinteger
Number of edges leaving the node.
nodes.elevationnumber
Elevation in meters.
nodes.intersection_typestring
regular, false for a node joining edges of one road, dead-end, or fork.

Allowed:regular, false, dead-end, fork

nodes.latnumber (double)
Latitude.
nodes.local_edge_countinteger
Number of edges leaving the node on the local road level.
nodes.lonnumber (double)
Longitude.
nodes.mode_changeboolean
Whether travelers can change mode here, as at a parking or bike-share node.
nodes.named_intersectionboolean
Whether the intersection has a name.
nodes.node_idobject
A graph identifier: the hierarchy level, the tile within it, and the object's index in that tile, plus value, all three packed into one integer.
nodes.private_accessboolean
Whether the node is on private land.
nodes.stop_indexinteger
Index of the transit stop. Transit nodes only.
nodes.tagged_accessboolean
Whether access comes from tags on the node rather than defaults.
nodes.traffic_signalboolean
Whether the node has a traffic signal.
nodes.transition_countinteger
Number of links to the same node on other road levels.
nodes.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

reasonstring
Why nothing was found. Verbose only, and present only when edges is null.

Example:No data found for location

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

Reference: Valhalla locate API reference