General options

All OSRM HTTP requests use a common structure.

The following syntax applies to all services, except as noted.

Requests

Passing any option=value is optional. polyline follows Google's polyline format with precision 5 by default and can be generated using this package.

To pass parameters to each location some options support an array like encoding:

Request options

Where the elements follow the following format:

{option}={element};{element}[;{element} ... ]

The number of elements must match exactly the number of locations (except for generate_hints and exclude). If you don't want to pass a value but instead use the default you can pass an empty element.

Example: 2nd location use the default value for option:

{option}={element};;{element}

Responses

Every response object has a code property containing one of the strings below or a service dependent code:

• message is a optional human-readable error message. All other status types are service dependent.
• In case of an error the HTTP status code will be 400. Otherwise the HTTP status code will be 200 and code will be Ok.

Every response object has a data_version propetry containing timestamp from the original OpenStreetMap file. This field is optional. It can be ommited if data_version parametr was not set on osrm-extract stage or OSM file has not osmosis_replication_timestamp section.

Services

Nearest service

Snaps a coordinate to the street network and returns the nearest n matches.

Where coordinates only supports a single {longitude},{latitude} entry.

In addition to the general options the following options are supported for this service:

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.

• waypoints array of Waypoint objects sorted by distance to the input coordinate. Each object has at least the following additional properties:

  • nodes: Array of OpenStreetMap node ids.

Route service

Finds the fastest route between coordinates in the supplied order.

In addition to the general options the following options are supported for this service:

* Please note that even if alternative routes are requested, a result cannot be guaranteed.

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• waypoints: Array of Waypoint objects representing all waypoints in order:
• routes: An array of Route objects, ordered by descending recommendation rank.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Table service

Computes the duration of the fastest route between all pairs of supplied coordinates. Returns the durations or distances or both between the coordinate pairs. Note that the distances are not the shortest distance between two coordinates, but rather the distances of the fastest routes. Duration is in seconds and distances is in meters.

Options

In addition to the general options the following options are supported for this service:

Unlike other array encoded options, the length of sources and destinations can be smaller or equal to number of input locations;

Example:

sources=0;5;7&destinations=5;1;4;2;3;6

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• durations array of arrays that stores the matrix in row-major order. durations[i][j] gives the travel time from the i-th waypoint to the j-th waypoint. Values are given in seconds. Can be null if no route between i and j can be found.
• distances array of arrays that stores the matrix in row-major order. distances[i][j] gives the travel distance from the i-th waypoint to the j-th waypoint. Values are given in meters. Can be null if no route between i and j can be found. Note that computing the distances table is currently only implemented for CH. If annotations=distance or annotations=duration,distance is requested when running a MLD router, a NotImplemented error will be returned.
• sources array of Waypoint objects describing all sources in order
• destinations array of Waypoint objects describing all destinations in order
• fallback_speed_cells (optional) array of arrays containing i,j pairs indicating which cells contain estimated values based on fallback_speed. Will be absent if fallback_speed is not used.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Match service

Map matching matches/snaps given GPS points to the road network in the most plausible way. Please note the request might result multiple sub-traces. Large jumps in the timestamps (> 60s) or improbable transitions lead to trace splits if a complete matching could not be found. The algorithm might not be able to match all points. Outliers are removed if they can not be matched successfully.

In addition to the general options the following options are supported for this service:

The radius for each point should be the standard error of the location measured in meters from the true location. Use Location.getAccuracy() on Android or CLLocation.horizontalAccuracy on iOS. This value is used to determine which points should be considered as candidates (larger radius means more candidates) and how likely each candidate is (larger radius means far-away candidates are penalized less). The area to search is chosen such that the correct candidate should be considered 99.9% of the time (for more details see this ticket).

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.

• tracepoints: Array of Waypoint objects representing all points of the trace in order. If the trace point was ommited by map matching because it is an outlier, the entry will be null. Each Waypoint object has the following additional properties:

  • matchings_index: Index to the Route object in matchings the sub-trace was matched to.
  • waypoint_index: Index of the waypoint inside the matched route.
  • alternatives_count: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching.

• matchings: An array of Route objects that assemble the trace. Each Route object has the following additional properties:

  • confidence: Confidence of the matching. float value between 0 and 1. 1 is very confident that the matching is correct.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Trip service

The trip plugin solves the Traveling Salesman Problem using a greedy heuristic (farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 waypoints. The returned path does not have to be the fastest path. As TSP is NP-hard it only returns an approximation. Note that all input coordinates have to be connected for the trip service to work.

In addition to the general options the following options are supported for this service:

Fixing Start and End Points

It is possible to explicitely set the start or end coordinate of the trip. When source is set to first, the first coordinate is used as start coordinate of the trip in the output. When destination is set to last, the last coordinate will be used as destination of the trip in the returned output. If you specify any, any of the coordinates can be used as the first or last coordinate in the output.

However, if source=any&destination=any the returned round-trip will still start at the first input coordinate by default.

Currently, not all combinations of roundtrip, source and destination are supported. Right now, the following combinations are possible:

• code: if the request was successful Ok otherwise see the service dependent and general status codes.

• waypoints: Array of Waypoint objects representing all waypoints in input order. Each Waypoint object has the following additional properties:

  • trips_index: Index to trips of the sub-trip the point was matched to.
  • waypoint_index: Index of the point in the trip.
• trips: An array of Route objects that assemble the trace.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Tile service

This service generates Mapbox Vector Tiles that can be viewed with a vector-tile capable slippy-map viewer. The tiles contain road geometries and metadata that can be used to examine the routing graph. The tiles are generated directly from the data in-memory, so are in sync with actual routing results, and let you examine which roads are actually routable, and what weights they have applied.

The x, y, and zoom values are the same as described at https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames, and are supported by vector tile viewers like Mapbox GL JS.

The response object is either a binary encoded blob with a Content-Type of application/x-protobuf, or a 404 error. Note that OSRM is hard-coded to only return tiles from zoom level 12 and higher (to avoid accidentally returning extremely large vector tiles).

Vector tiles contain two layers:

speeds layer:

turns layer:

Result objects

Route object

Represents a route through (potentially multiple) waypoints.

Properties

• distance: The distance traveled by the route, in float meters.
• duration: The estimated travel time, in float number of seconds.
• geometry: The whole geometry of the route value depending on overview parameter, format depending on the geometries parameter. See RouteStep's geometry property for a parameter documentation.
• weight: The calculated weight of the route.
• weight_name: The name of the weight profile used during extraction phase.

• legs: The legs between the given waypoints, an array of RouteLeg objects.

Three input coordinates, geometry=geojson, steps=false:

RouteLeg object

Represents a route between two waypoints.

Properties

• distance: The distance traveled by this route leg, in float meters.
• duration: The estimated travel time, in float number of seconds.
• weight: The calculated weight of the route leg.
• summary: Summary of the route taken as string. Depends on the summary parameter:

• steps: Depends on the steps parameter.

• annotation: Additional details about each coordinate along the route geometry:

With steps=false and annotations=true:

Annotation object

Annotation of the whole route leg with fine-grained information about each segment or node id.

Properties

• distance: The distance, in metres, between each pair of coordinates
• duration: The duration between each pair of coordinates, in seconds. Does not include the duration of any turns.
• datasources: The index of the datasource for the speed between each pair of coordinates. 0 is the default profile, other values are supplied via --segment-speed-file to osrm-contract or osrm-customize. String-like names are in the metadata.datasource_names array.
• nodes: The OSM node ID for each coordinate along the route, excluding the first/last user-supplied coordinates
• weight: The weights between each pair of coordinates. Does not include any turn costs.
• speed: Convenience field, calculation of distance / duration rounded to one decimal place

• metadata: Metadata related to other annotations

  • datasource_names: The names of the datasources used for the speed between each pair of coordinates. lua profile is the default profile, other values arethe filenames supplied via --segment-speed-file to osrm-contract or osrm-customize

RouteStep object

A step consists of a maneuver such as a turn or merge, followed by a distance of travel along a single way to the subsequent step.

Properties

• distance: The distance of travel from the maneuver to the subsequent step, in float meters.
• duration: The estimated travel time, in float number of seconds.
• geometry: The unsimplified geometry of the route segment, depending on the geometries parameter.
• weight: The calculated weight of the step.

• name: The name of the way along which travel proceeds.
• ref: A reference number or code for the way. Optionally included, if ref data is available for the given way.
• pronunciation: A string containing an IPA phonetic transcription indicating how to pronounce the name in the name property. This property is omitted if pronunciation data is unavailable for the step.
• destinations: The destinations of the way. Will be undefined if there are no destinations.
• exits: The exit numbers or names of the way. Will be undefined if there are no exit numbers or names.
• mode: A string signifying the mode of transportation.
• maneuver: A StepManeuver object representing the maneuver.
• intersections: A list of Intersection objects that are passed along the segment, the very first belonging to the StepManeuver
• rotary_name: The name for the rotary. Optionally included, if the step is a rotary and a rotary name is available.
• rotary_pronunciation: The pronunciation hint of the rotary name. Optionally included, if the step is a rotary and a rotary pronunciation is available.
• driving_side: The legal driving side at the location for this step. Either left or right.

StepManeuver object

Properties

• location: A [longitude, latitude] pair describing the location of the turn.
• bearing_before: The clockwise angle from true north to the direction of travel immediately before the maneuver. Range 0-359.
• bearing_after: The clockwise angle from true north to the direction of travel immediately after the maneuver. Range 0-359.
• type A string indicating the type of maneuver. new identifiers might be introduced without API change Types unknown to the client should be handled like the turn type, the existence of correct modifier values is guranteed.

Please note that even though there are new name and notification instructions, the mode and name can change between all instructions. They only offer a fallback in case nothing else is to report.

• modifier An optional string indicating the direction change of the maneuver.

The list of turns without a modifier is limited to: depart/arrive. If the source/target location is close enough to the depart/arrive location, no modifier will be given.

The meaning depends on the type property.

• exit An optional integer indicating number of the exit to take. The property exists for the roundabout / rotary property: Number of the roundabout exit to take. If exit is undefined the destination is on the roundabout.

New properties (potentially depending on type) may be introduced in the future without an API version change.

Lane object

A Lane represents a turn lane at the corresponding turn location.

Properties

• indications: a indication (e.g. marking on the road) specifying the turn lane. A road can have multiple indications (e.g. an arrow pointing straight and left). The indications are given in an array, each containing one of the following types. Further indications might be added on without an API version change.

• valid: a boolean flag indicating whether the lane is a valid choice in the current maneuver

Intersection object

An intersection gives a full representation of any cross-way the path passes bay. For every step, the very first intersection (intersections[0]) corresponds to the location of the StepManeuver. Further intersections are listed for every cross-way until the next turn instruction.

Properties

• location: A [longitude, latitude] pair describing the location of the turn.
• bearings: A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. Values are between 0-359 (0=true north)
• classes: An array of strings signifying the classes (as specified in the profile) of the road exiting the intersection.
• entry: A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of true indicates that the respective road could be entered on a valid route. false indicates that the turn onto the respective road would violate a restriction.
• in: index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for depart maneuvers.
• out: index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for arrive maneuvers.
• lanes: Array of Lane objects that denote the available turn lanes at the intersection. If no lane information is available for an intersection, the lanes property will not be present.

Waypoint object

Object used to describe waypoint on a route.

Properties

• name Name of the street the coordinate snapped to
• location Array that contains the [longitude, latitude] pair of the snapped coordinate
• distance The distance, in metres, from the input coordinate to the snapped coordinate
• hint Unique internal identifier of the segment (ephemeral, not constant over data updates) This can be used on subsequent request to significantly speed up the query and to connect multiple services. E.g. you can use the hint value obtained by the nearest query as hint values for route inputs.

Introduction

OSRM can be used as a library (libosrm) via C++ instead of using it through the HTTP interface and osrm-routed. This allows for fine-tuning OSRM and has much less overhead. Here is a quick introduction into how to use libosrm in the upcoming v5 release.

Take a look at the example code that lives in the example directory. Here is all you ever wanted to know about libosrm, that is a short description of what the types do and where to find documentation on it:

Important interface objects

• EngineConfig - for initializing an OSRM instance we can configure certain properties and constraints. E.g. the storage config is the base path such as france.osm.osrm from which we derive and load france.osm.osrm.* auxiliary files. This also lets you set constraints such as the maximum number of locations allowed for specific services.

• OSRM - this is the main Routing Machine type with functions such as Route and Table. You initialize it with a EngineConfig. It does all the heavy lifting for you. Each function takes its own parameters, e.g. the Route function takes RouteParameters, and a out-reference to a JSON result that gets filled. The return value is a Status, indicating error or success.

• Status - this is a type wrapping Error or Ok for indicating error or success, respectively.

• TableParameters - this is an example of parameter types the Routing Machine functions expect. In this case Table expects its own parameters as TableParameters. You can see it wrapping two vectors, sources and destinations --- these are indices into your coordinates for the table service to construct a matrix from (empty sources or destinations means: use all of them). If you ask yourself where coordinates come from, you can see TableParameters inheriting from BaseParameters.

• BaseParameter - this most importantly holds coordinates (and a few other optional properties that you don't need for basic usage); the specific parameter types inherit from BaseParameters to get these member attributes. That means your TableParameters type has coordinates, sources and destination member attributes (and a few other that we ignore for now).

• Coordinate - this is a wrapper around a (longitude, latitude) pair. We really don't care about (lon,lat) vs (lat, lon) but we don't want you to accidentally mix them up, so both latitude and longitude are strictly typed wrappers around integers (fixed notation such as 13423240) and floating points (floating notation such as 13.42324).

• Parameters for other services - here are all other *Parameters you need for other Routing Machine services.

• JSON - this is a sum type resembling JSON. The Routing Machine service functions take a out-ref to a JSON result and fill it accordingly. It is currently implemented using mapbox/variant which is similar to Boost.Variant. There are two ways to work with this sum type: either provide a visitor that acts on each type on visitation or use the get function in case you're sure about the structure. The JSON structure is written down in the HTTP API.

Example

See the example folder in the OSRM repository.

Workflow

• Create an OSRM instance initialized with a EngineConfig
• Call the service function on the OSRM object providing service specific *Parameters
• Check the return code and use the JSON result