Skip to content

Valhalla locate service API reference

Valhalla's locate service is an open-source service that provides detailed information about streets and intersections close to an input point with some added matching criteria. This allows for tight integration in routing and navigation applications on web or mobile.

View an interactive demo

The default logic for the OpenStreetMap tags, keys, and values used when routing are documented on an OSM wiki page.

Inputs of a locate request

The locate request run locally takes the form of localhost:8002/locate?json={}, where the JSON inputs inside the {} include location information, name and options for the costing model, and output options. Here is the JSON payload for an example request:

{"verbose":true,"locations":[{"lat":42.358528,"lon":-83.271400},{"lat":42.996613,"lon":-78.749855}],"costing":"bicycle","costing_options":{"bicycle":{"bicycle_type":"road"}},"directions_options":{"units":"miles"},"id":"12abc3afe23984fe"}

This request provides detailed information about specific streets and intersections near the two input locations. Steets which do not have a surface type condusive to road bicycles will be excluded from the results. The units used for the lengths of the street sections will be displayed in miles.

There is an option to name your request. You can do this by adding and id key to your request. The id is returned with the response so a user could match to the corresponding request.

Because the locate service is designed to work in tandem with the route service API, the inputs for the two APIs are identical. For detailed options regarding specifying locations, costing models, costing options, directions options please see the relevant sections in the routing API docs

Other request options

Options Description
verbose Can be set to true or false, but defaults to false. If set to true dense attribution of the given street or intersection will be returned.
id Name your route request. If id is specified, the naming will be sent through to the response.

Outputs of a locate request

If a request has been named using the optional id key, then this id key and value will be echoed in the JSON response object.

The locate results are returned as a JSON array, with one JSON object per input location in the order specified. In verbose mode details about the streets and intersections including mode of travel access, names, way ids, shape, side of street as well as the closest point to the input along these features will be returned. If verbose was not enabled only the closest point, way id and side of street will be returned. A warnings array may also be included. This array may contain warning objects informing about deprecated request parameters, clamped values etc. |

Here are some sample results with verbose set to false:

[
  {
    "input_lon": -76.495743,
    "input_lat": 40.310555,
    "nodes": [
      {
        "lat": 40.313206,
        "lon": -76.494987
      }
    ],
    "edges": [
      {
        "way_id": 12292268,
        "correlated_lat": 40.313206,
        "side_of_street": "neither",
        "percent_along": 0,
        "correlated_lon": -76.494987
      },
      {
        "way_id": 12292268,
        "correlated_lat": 40.313206,
        "side_of_street": "neither",
        "percent_along": 1,
        "correlated_lon": -76.494987
      }
    ],
    "warnings": [
      "hov costing is deprecated and will be turned into auto costing with hov2=true costing option"
    ]
  }
]

Here are some sample results with verbose set to true (the 2016-value predicted_speeds array is shortened):

[
  {
    "input_lat": 50.916223,
    "input_lon": 6.915118,
    "edges": [
      {
        "access_restrictions": [],
        "live_speed": {},
        "correlated_lat": 50.916151,
        "correlated_lon": 6.915217,
        "side_of_street": "left",
        "bounding_circle": {
          "lat": 50.916182,
          "lon": 6.915271,
          "radius": 50
        },
        "linear_reference": "KwTqzCQ09XPEAQBhADczVHU=",
        "percent_along": 0.45856,
        "distance": 10.5,
        "shoulder": false,
        "heading": 48.7,
        "outbound_reach": 100,
        "inbound_reach": 100,
        "edge_info": {
          "way_id": 24326584,
          "bike_network": {
            "national": false,
            "regional": false,
            "local": false,
            "mountain": false
          },
          "names": [
            "Hollerather Straße"
          ],
          "shape": "kctb`Bwl`eLc`@{z@",
          "mean_elevation": 52,
          "speed_limit": 30,
          "osm_node_ids": [
            8307867174,
            8307867178
          ]
        },
        "edge": {
          "end_node": {
            "level": 2,
            "tile_id": 811467,
            "id": 44240,
            "value": 1484454563418
          },
          "speeds": {
            "default": 15,
            "type": "classified",
            "free_flow": 0,
            "constrained_flow": 0,
            "predicted": false
          },
          "access_restriction": false,
          "start_restriction": {
            "bicycle": false,
            "bus": false,
            "car": false,
            "emergency": false,
            "HOV": false,
            "pedestrian": false,
            "taxi": false,
            "truck": false,
            "wheelchair": false,
            "moped": false,
            "motorcycle": false
          },
          "end_restriction": {
            "bicycle": false,
            "bus": false,
            "car": false,
            "emergency": false,
            "HOV": false,
            "pedestrian": false,
            "taxi": false,
            "truck": false,
            "wheelchair": false,
            "moped": false,
            "motorcycle": false
          },
          "part_of_complex_restriction": false,
          "has_sign": false,
          "toll": false,
          "destination_only": false,
          "destination_only_hgv": false,
          "tunnel": false,
          "bridge": false,
          "round_about": false,
          "traffic_signal": false,
          "forward": true,
          "not_thru": false,
          "stop_sign": false,
          "yield_sign": false,
          "cycle_lane": "none",
          "bike_network": false,
          "truck_route": false,
          "lane_count": 1,
          "country_crossing": false,
          "sidewalk_left": true,
          "sidewalk_right": true,
          "sac_scale": "none",
          "deadend": false,
          "geo_attributes": {
            "length": 89,
            "weighted_grade": 0,
            "max_up_slope": 1,
            "max_down_slope": 0,
            "curvature": 0
          },
          "access": {
            "bicycle": true,
            "bus": true,
            "car": true,
            "emergency": false,
            "HOV": true,
            "pedestrian": true,
            "taxi": true,
            "truck": true,
            "wheelchair": true,
            "moped": true,
            "motorcycle": true
          },
          "classification": {
            "classification": "residential",
            "use": "road",
            "surface": "paved_smooth",
            "link": false,
            "internal": false
          }
        },
        "edge_id": {
          "level": 2,
          "tile_id": 811467,
          "id": 107643,
          "value": 3611906215514
        },
        "predicted_speeds": []
      }
    ],
    "nodes": []
  }
]

If no edges can be found for a location, edges and nodes are null. In verbose mode a reason string is added as well.

Attribute Descriptions for Responses

Lengths and distances are in meters, speeds in kilometers per hour, angles in degrees, unless stated otherwise.

Location

Key Description
input_lat, input_lon The input coordinate.
edges The edges the location correlated to.
filtered_edges Only present if non-empty. Edges near the location that were dropped by the location's heading or search_filter.level filter. Same format as edges.
nodes The end nodes of correlated edges, if the location snapped onto a node. Empty if it snapped to the middle of an edge.
reason Verbose only. Why nothing was found for this location.

Edge (verbose)

Key Description
incidents Only present if the edge carries live traffic incidents. One object per incident with id, type, description, long_description, creation_time, start_time, end_time, impact, sub_type, sub_type_description, alertc_codes, lanes_blocked, num_lanes_blocked, clear_lanes, length, closed, congestion, iso_3166_1_alpha2, iso_3166_1_alpha3. Fields without a value are omitted.
access_restrictions Access restrictions on the edge. See Access restriction.
live_speed Live traffic speed, empty if the edge has no valid live speed. See Live speed.
correlated_lat, correlated_lon The point on the edge the input was snapped to.
side_of_street left, right or neither: on which side of the edge the input lies, relative to the edge's direction.
bounding_circle lat, lon and radius of the circle enclosing the edge's shape, as stored in the tile. radius is 0 if the tileset has no bounding circles.
linear_reference Base64 OpenLR line location reference for the whole edge, with the positive offset set to percent_along.
percent_along Position of the correlated point along the edge, from 0 to 1.
distance Distance from the input to the correlated point.
shoulder A boolean value indicating whether the edge has shoulder (true or false). If true then the data has been tagged to indicate a shoulder is present. false, however, could mean either that the data is tagged as having no shoulder present OR the data is untagged and we assume no shoulder (which may be an incorrect assumption)
heading Heading of the edge at the correlated point, clockwise from north.
outbound_reach, inbound_reach Number of edges reachable from / that can reach this edge, counted up to the location's minimum_reachability.
edge_info Data shared by the edge and its opposing edge. See Edge info.
edge Attributes of the directed edge. See Directed edge.
edge_id The edge's graph id. See Graph id.
timed_predicted_speed Only present if the location has a date_time and the edge has predicted speeds. The predicted speed at that time.
predicted_speeds The edge's predicted speeds for the whole week in 5-minute buckets (2016 values), starting Sunday 00:00 local time. Empty if the edge has no predicted speeds.

Edge (non-verbose)

Key Description
way_id OSM way id of the edge.
correlated_lat, correlated_lon, side_of_street, percent_along As in verbose mode.

Live speed

All keys are absent if the edge has no valid live speed. An edge is split into up to three subsegments.

Key Description
overall_speed Speed over the whole edge.
speed_0, speed_1, speed_2 Speed on each subsegment, null if unknown.
congestion_0, congestion_1, congestion_2 Congestion on each subsegment from 0 (free flow) to 1 (stopped), null if unknown.
breakpoint_0, breakpoint_1 Where the first and second subsegments end, as a fraction of the edge length.

Edge info

Key Description
way_id OSM way id.
bike_network Booleans national, regional, local, mountain: which bicycle route networks the way is part of.
names Street names, refs etc.
shape Edge geometry as an encoded polyline with 6 digits of precision, in the direction the edge info was stored (see edge.forward).
mean_elevation Mean elevation in meters, null if there's no elevation data.
speed_limit The edge's speed limit, 0 if unknown, "unlimited" if there's none.
conditional_speed_limits Only present if tagged. The key describes the time window during which the speed limit applies, the value is the limit.
levels Only present if tagged. An array containing the edge's levels as derived from the level=* tag. Values are either numeric, or another array containing two elements, which denote the start and end of a range (inclusive).
osm_node_ids Only present if the tileset was built to store them. OSM node ids along the edge's shape.

Directed edge

Key Description
end_node Graph id of the node the edge ends at. See Graph id.
speeds.default The base speed used when no traffic speed applies.
speeds.type tagged if the default speed comes from a maxspeed tag, classified if it was derived from the road class.
speeds.free_flow, speeds.constrained_flow Historical night-time and day-time speed, 0 if not set.
speeds.predicted Whether the edge has predicted (historical) speed profiles.
access_restriction Whether the edge has entries in access_restrictions.
start_restriction, end_restriction Per mode: whether a complex (via-way) turn restriction starts / ends on this edge.
part_of_complex_restriction Whether the edge is inside (a via-way of) a complex restriction.
has_sign Whether the edge has exit signs or guidance signs.
toll, tunnel, bridge, round_about As the names say.
destination_only Access is only allowed to reach a destination on it (e.g. access=destination, private roads).
destination_only_hgv As destination_only, but for trucks only.
traffic_signal, stop_sign, yield_sign Whether there's a traffic signal / stop sign / yield sign at the end of the edge.
forward Whether the edge runs in the same direction as the shape in edge_info.
not_thru The edge leads into a region with no exit (no through traffic).
cycle_lane none, shared, dedicated or separated.
bike_network Whether the edge is part of any bicycle route network.
truck_route Whether the edge is part of a designated truck route.
lane_count Number of lanes in this direction.
country_crossing Whether the edge crosses a country border.
sidewalk_left, sidewalk_right Whether there's a sidewalk on the left / right side.
sac_scale Hiking difficulty: none, hiking, mountain hiking, demanding mountain hiking, alpine hiking, demanding alpine hiking, difficult alpine hiking.
deadend Whether the edge ends in a dead end.
geo_attributes.length Edge length.
geo_attributes.weighted_grade Length-weighted grade in percent, from -10 to 15.
geo_attributes.max_up_slope, geo_attributes.max_down_slope Steepest up- and downhill slope in degrees.
geo_attributes.curvature Curvature factor from 0 (straight) to 15.
access Per mode: whether the mode may travel along this edge in its direction.
classification.classification Road class: motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_other.
classification.use What the edge is used for, e.g. road, ramp, turn_channel, driveway, footway, cycleway, ferry, rail.
classification.surface paved_smooth, paved, paved_rough, compacted, dirt, gravel, path, impassable.
classification.link Whether the edge is a *_link road.
classification.internal Whether the edge is internal to an intersection.
hov_type Only present on HOV-only edges: HOV-2 or HOV-3.

Access restriction

Key Description
type hazmat, max_height, max_width, max_length, max_weight, max_axle_load, timed_allowed, timed_denied, destination_allowed or max_axles.
edge_index Index of the edge inside its tile.
bus, car, emergency, HOV, pedestrian, taxi, truck, wheelchair, moped, motorcycle Whether the restriction applies to this mode.
except_destination Whether the restriction is lifted when using the edge is necessary to reach the destination.
value For max_* dimension types: the limit in meters or metric tons. For max_axles: the number of axles. For hazmat: a boolean. For timed_allowed, timed_denied and destination_allowed: an object whose time_domain is the encoded time window.

Node (verbose)

Key Description
lat, lon Node position.
elevation Node elevation.
edge_count Number of outbound edges from this node in its tile.
access Object with a boolean access value per mode.
tagged_access Whether the node's access was set by OSM tags instead of defaults.
intersection_type regular, false, dead-end or fork.
administrative iso_3166-1, country, iso_3166-2, state and time_zone_name (IANA name) of the node's location.
density Graph ensity around the node, from 0 to 15.
local_edge_count Number of edges across all hierarchy levels.
drive_on_right Whether traffic drives on the right.
mode_change Whether travel mode can change here.
private_access Whether the node is tagged as private.
traffic_signal Whether the node has a traffic signal.
type street_intersection, gate, bollard, toll_booth, toll_gantry, border_control, motor_way_junction, parking, bike_share, transit_egress, transit_station, multi_use_transit_platform, sump_buster, building_entrance or elevator.
transition_count Number of transitions to the same node on other hierarchy levels.
named_intersection Whether the intersection has a name.
stop_index Only present on transit nodes. Index of the transit stop in the tile.
node_id The node's graph id. See Graph id.

Node (non-verbose)

Key Description
lat, lon Node position.

Graph id

Key Description
level Hierarchy level: 0 (highways), 1 (arterials), 2 (local), 3 (transit).
tile_id Tile index within the level.
id Index of the edge or node within the tile.
value The full 64-bit id, as used elsewhere in the API.

HTTP status codes and error messages

Because the locate service API is so tightly integrated with the route service API the two share the same list of response codes and error messages. Please review the full lists in the routing service API documentation