Valhalla routing service API reference

Valhalla’s routing service (a.k.a. turn-by-turn), is an open-source routing service that lets you integrate routing and navigation into a web or mobile application.

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 route

The route request run locally takes the form of localhost:8002/route?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:

{"locations":[{"lat":42.358528,"lon":-83.271400,"street":"Appleton"},{"lat":42.996613,"lon":-78.749855,"street":"Ranch Trail"}],"costing":"auto","costing_options":{"auto":{"country_crossing_penalty":2000.0}},"units":"miles","id":"my_work_route"}

This request provides automobile routing between the Detroit, Michigan area and Buffalo, New York, with an optional street name parameter to improve navigation at the start and end points. It attempts to avoid routing north through Canada by adding a penalty for crossing international borders. The resulting route is displayed in miles.

There is an option to name your route request. You can do this by appending the following to your request &id=. The id is returned with the response so a user could match to the corresponding request.

Locations

You specify locations as an ordered list of two or more locations within a JSON array. Locations are visited in the order specified.

A location must include a latitude and longitude in decimal degrees. The coordinates can come from many input sources, such as a GPS location, a point or a click on a map, a geocoding service, and so on. Note that the Valhalla cannot search for names or addresses or perform geocoding or reverse geocoding. External search services, such as Mapbox Geocoding , can be used to find places and geocode addresses, which must be converted to coordinates for input.

To build a route, you need to specify two break locations. In addition, you can include through, via or break_through locations to influence the route path.

Optionally, you can include the following location information without impacting the routing. This information is carried through the request and returned as a convenience.

• name = Location or business name. The name may be used in the route narration directions, such as “You have arrived at <business name>.“)
• city = City name.
• state = State name.
• postal_code = Postal code.
• country = Country name.
• phone = Telephone number.
• url = URL for the place or location.
• waiting: The waiting time in seconds at this location. E.g. when the route describes a pizza delivery tour, each location has a service time, which can be respected by setting waiting on the location, then the departure will be delayed by this amount in seconds. Only works for break or break_through types.
• side_of_street = (response only) The side of street of a break location that is determined based on the actual route when the location is offset from the street. The possible values are left and right.
• date_time = (response only for /route) Expected date/time for the user to be at the location using the ISO 8601 format (YYYY-MM-DDThh:mm) in the local time zone of departure or arrival. For example “2015-12-29T08:00”. If waiting was set on this location in the request, and it’s an intermediate location, the date_time will describe the departure time at this location.

Future development work includes adding location options and information related to time at each location. This will allow routes to specify a start time or an arrive by time at each location. There is also ongoing work to improve support for through locations.

Costing models

Valhalla’s routing service uses dynamic, run-time costing to generate the route path. The route request must include the name of the costing model and can include optional parameters available for the chosen costing model.

Costing options

Costing methods can have several options that can be adjusted to develop the route path, as well as for estimating time along the path. Specify costing model options in your request using the format of costing_options.type, such as costing_options.auto.

• Cost options are fixed costs in seconds that are added to both the path cost and the estimated time. Examples of costs are gate_costs and toll_booth_costs, where a fixed amount of time is added. Costs are not generally used to influence the route path; instead, use penalties to do this. Costs must be in the range of 0.0 seconds to 43200.0 seconds (12 hours), otherwise a default value will be assigned.
• Penalty options are fixed costs in seconds that are only added to the path cost. Penalties can influence the route path determination but do not add to the estimated time along the path. For example, add a toll_booth_penalty to create route paths that tend to avoid toll booths. Penalties must be in the range of 0.0 seconds to 43200.0 seconds (12 hours), otherwise a default value will be assigned.
• Factor options are used to multiply the cost along an edge or road section in a way that influences the path to favor or avoid a particular attribute. Factor options do not impact estimated time along the path, though. Factors must be in the range 0.1 to 100000.0, where factors of 1.0 have no influence on cost. Anything outside of this range will be assigned a default value. Use a factor less than 1.0 to attempt to favor paths containing preferred attributes, and a value greater than 1.0 to avoid paths with undesirable attributes. Avoidance factors are more effective than favor factors at influencing a path. A factor’s impact also depends on the length of road containing the specified attribute, as longer roads have more impact on the costing than very short roads. For this reason, penalty options tend to be better at influencing paths.

A special costing option is shortest, which, when true, will solely use distance as cost and disregard all other costs, penalties and factors. It’s available for all costing models except multimodal & bikeshare.

Another special case is disable_hierarchy_pruning costing option. As the name indicates, disable_hierarchy_pruning = true will disable hierarchies in routing algorithms, which allows us to find the actual optimal route even in edge cases. For example, together with shortest = true they can find the actual shortest route. When disable_hierarchy_pruning is true and arc distances between source and target are not above the max limit, the actual optimal route will be calculated at the expense of performance. Note that if arc distances between locations exceed the max limit, disable_hierarchy_pruning is true will not be applied. This costing option is available for all motorized costing models, i.e auto, motorcycle, motor_scooter, bus, truck & taxi. For bicycle and pedestrian hierarchies are always disabled by default.

Additionally to the main costing option, the recostings option can be used to calculate the travelling time of the found route based on different costing options. By e.g. adding

"recostings":[
    {"costing":"auto","fixed_speed":20,"name":"auto_20"},
    {"costing":"auto","fixed_speed":50,"name":"auto_50"}
]

to the route request, the values time_auto_20 and time_auto_50 will be added to summaries to show how much time the route would cost with these given costing options. Passing a recosting which make the route impossible to follow (e.g. the main rout is by car over a motorway and recosting with pedestrian costing) leads to a none result of this recosting.

Automobile and bus costing options

These options are available for auto, bus, and truck costing methods.

Other costing options

The following options are available for auto, bus, taxi, and truck costing methods.

The following options are available for truck costing.

Bicycle costing options

The default bicycle costing is tuned toward road bicycles with a slight preference for using cycleways  or roads with bicycle lanes. Bicycle routes use regular roads where needed or where no direct bicycle lane options exist, but avoid roads without bicycle access. The costing model recognizes several factors unique to bicycle travel and offers several options for tuning bicycle routes. Several factors unique to travel by bicycle influence the resulting route.

• The types of roads suitable for bicycling depend on the type of bicycle. Road bicycles (skinny or narrow tires) generally are suited to paved roads or perhaps very short sections of compacted gravel. They are not designed for riding on coarse gravel or most paths and tracks through wooded areas or farmland. Mountain bikes, on the other hand, are able to traverse a wider set of surfaces.
• Average travel speed can be highly variable and can depend on bicycle type, fitness and experience of the cyclist, road surface, and hills. The costing model assumes a default speed on smooth, flat roads for each supported bicycle type. This speed can be overridden by an input option. The base speed is modulated by surface type (in conjunction with the bicycle type). In addition, speed is modified based on the hilliness of a road section.
• Bicyclists vary in their tolerance for riding on roads. Most novice bicyclists, and even other bicyclists, prefer cycleways and dedicated cycling paths and would rather avoid all but the quietest neighborhood roads. Other cyclists may be experienced riding on roads and prefer to take roadways because they often provide the fastest way to get between two places. The bicycle costing model accounts for this with a use_roads factor to indicate a cyclist’s tolerance for riding on roads.
• Bicyclists vary in their fitness level and experience level, and many want to avoid hilly roads, and especially roads with very steep uphill or even downhill sections. Even if the fastest path is over a mountain, many cyclists prefer a flatter path that avoids the climb and descent up and over the mountain.

The following options described above for autos also apply to bicycle costing methods: maneuver_penalty, gate_cost, gate_penalty, destination_only_penalty , country_crossing_cost, country_costing_penalty, and service_penalty.

These additional options are available for bicycle costing methods.

Motor_scooter costing options

Standard costing for travel by motor scooter or moped. By default, motor_scooter costing will avoid higher class roads unless the country overrides allows motor scooters on these roads. Motor scooter routes follow regular roads when needed, but avoid roads without motor_scooter, moped, or mofa access. The costing model recognizes factors unique to motor_scooter travel and offers options for tuning motor_scooter routes. Factors unique to travel by motor_scooter influence the resulting route.

All of the options described above for autos also apply to motor_scooter costing methods. These additional options are available for motor_scooter costing methods.

Motorcycle costing options -> BETA

Standard costing for travel by motorcycle. By default, motorcycle costing will default to higher class roads. The costing model recognizes factors unique to motorcycle travel and offers options for tuning motorcycle routes.

All of the options described above for autos also apply to motorcycle costing methods. The following options are available for motorcycle costing:

Pedestrian costing options

These options are available for pedestrian costing methods.

Transit costing options

These options are available for transit costing when the multimodal costing model is used.

Sample JSON payloads for multimodal requests with transit

A multimodal request at the current date and time:

{"locations":[{"lat":40.730930,"lon":-73.991379,"street":"Wanamaker Place"},{"lat":40.749706,"lon":-73.991562,"street":"Penn Plaza"}],"costing":"multimodal","units":"miles"}

A multimodal request departing on 2016-03-29 at 08:00:

{"locations":[{"lat":40.749706,"lon":-73.991562,"type":"break","street":"Penn Plaza"},{"lat":40.73093,"lon":-73.991379,"type":"break","street":"Wanamaker Place"}],"costing":"multimodal","date_time":{"type":1,"value":"2016-03-29T08:00"}}

A multimodal request for a route favoring buses and a person walking at a set speed of 4.1 km/h:

{"locations":[{"lat":40.749706,"lon":-73.991562,"type":"break","street":"Penn Plaza"},{"lat":40.73093,"lon":-73.991379,"type":"break","street":"Wanamaker Place"}],"costing":"multimodal","costing_options":{"transit":{"use_bus":"1.0","use_rail":"0.0","use_transfers":"0.3"},"pedestrian":{"walking_speed":"4.1"}}}

A multimodal request with a filter for certain Onestop IDs:

{"locations":[{"lat":40.730930,"lon":-73.991379,"street":"Wanamaker Place"},{"lat":40.749706,"lon":-73.991562,"street":"Penn Plaza"}],"costing":"multimodal","costing_options":{"transit":{"filters":{"routes":{"ids":["NYC_AUR"],"action":"exclude"},"operators":{"ids":["paris_CFG","berlin_VBB"],"action":"include"}}}},"units":"miles"}

Directions options

Directions options should be specified at the top level of the JSON object.

For example a bus request with the result in Spanish using the OSRM (Open Source Routing Machine) format with the additional bannerInstructions and voiceInstructions in the steps would use the following json:

{"locations":[{"lat":40.730930,"lon":-73.991379},{"lat":40.749706,"lon":-73.991562}],"format":"osrm","costing":"bus","banner_instructions":true,"voice_instructions":true,"language":"es-ES"}

Supported language tags

Other request options

Outputs of a route

If a route has been named in the request using the optional &id= input, then the name will be returned as a string id on the JSON object.

The route results are returned as a trip. This is a JSON object that contains details about the trip, including locations, a summary with basic information about the entire trip, and a list of legs.

Basic trip information includes:

The summary JSON object includes:

Trip legs and maneuvers

A trip contains one or more legs. For n number of break locations, there are n-1 legs. Through locations do not create separate legs.

Each leg of the trip includes a summary, which is comprised of the same information as a trip summary but applied to the single leg of the trip. It also includes a shape, which is an encoded polyline  of the route path (with 6 digits decimal precision), and a list of maneuvers as a JSON array. For more about decoding route shapes, see these code examples.

If elevation_interval is specified, each leg of the trip will return elevation along the route as a JSON array. The elevation_interval is also returned. Units for both elevation and elevation_interval are either meters or feet based on the input units specified.

Each maneuver includes:

For the maneuver type, the following are available:

kNone = 0;
kStart = 1;
kStartRight = 2;
kStartLeft = 3;
kDestination = 4;
kDestinationRight = 5;
kDestinationLeft = 6;
kBecomes = 7;
kContinue = 8;
kSlightRight = 9;
kRight = 10;
kSharpRight = 11;
kUturnRight = 12;
kUturnLeft = 13;
kSharpLeft = 14;
kLeft = 15;
kSlightLeft = 16;
kRampStraight = 17;
kRampRight = 18;
kRampLeft = 19;
kExitRight = 20;
kExitLeft = 21;
kStayStraight = 22;
kStayRight = 23;
kStayLeft = 24;
kMerge = 25;
kRoundaboutEnter = 26;
kRoundaboutExit = 27;
kFerryEnter = 28;
kFerryExit = 29;
kTransit = 30;
kTransitTransfer = 31;
kTransitRemainOn = 32;
kTransitConnectionStart = 33;
kTransitConnectionTransfer = 34;
kTransitConnectionDestination = 35;
kPostTransitConnectionDestination = 36;
kMergeRight = 37;
kMergeLeft = 38;
kElevatorEnter = 39;
kStepsEnter = 40;
kEscalatorEnter = 41;
kBuildingEnter = 42;
kBuildingExit = 43;

The maneuver sign may contain four lists of interchange sign elements as follows:

• exit_number_elements = list of exit number elements. If an exit number element exists, it is typically just one value.
• exit_branch_elements = list of exit branch elements. The exit branch element text is the subsequent road name or route number after the sign.
• exit_toward_elements = list of exit toward elements. The exit toward element text is the location where the road ahead goes - the location is typically a control city, but may also be a future road name or route number.
• exit_name_elements = list of exit name elements. The exit name element is the interchange identifier - typically not used in the US.

Each maneuver sign element includes:

A maneuver transit_info includes:

A transit_stop includes:

Continuing with the earlier routing example from the Detroit, Michigan area, a maneuver such as this one may be returned with that request: {"begin_shape_index":0,"length":0.109,"end_shape_index":1,"instruction":"Go south on Appleton.","street_names":["Appleton"],"type":1,"time":0}

In the future, look for additional maneuver information to enhance navigation applications, including landmark usage.

HTTP status codes and conditions

The following is a table of HTTP status error code conditions that may occur for a particular request. In general, the service follows the HTTP specification . That is to say that 5xx returns are generally ephemeral server problems that should be resolved shortly or are the result of a bug. 4xx returns are used to mark requests that cannot be carried out, generally due to bad input in the request or problems with the underlying data. A 2xx return is expected when there is a successful route result or trip, as described above.

Internal error codes and conditions

The following is a table of exception internal error code conditions that may occur for a particular request. An error code utility header file  can be included by any of the Valhalla service projects.

The codes correspond to code returned from a particular Valhalla project .