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

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 : An array of Route objects that assemble the trace. Each Route object has the following additional properties:

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

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:

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

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

Example Requests

# Round trip in Berlin with three stops:
curl 'http://router.project-osrm.org/trip/v1/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219'

# Round trip in Berlin with four stops, starting at the first stop, ending at the last:
curl 'http://router.project-osrm.org/trip/v1/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219;13.418555,52.523215?source=first&destination=last'

Response

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:

Example request

# This fetches a Z=13 tile for downtown San Francisco:
curl 'http://router.project-osrm.org/tile/v1/car/tile(1310,3166,13).mvt'

Example response

Represents a route through (potentially multiple) waypoints.

Properties

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

Represents a route between two waypoints.

Properties

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

Properties

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

Properties

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.

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.

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

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

Properties

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

Object used to describe waypoint on a route.

Properties

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:

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 .

See the example folder in the OSRM repository.