node osrm api

Node API

Service	Description
route	shortest path between given coordinates
nearest	returns the nearest street segment for a given coordinate
table	computes distance tables for given coordinates
match	matches given coordinates to the road network
trip	Compute the shortest round trip between given coordinates
tile	Return vector tiles containing debugging info

General options

The following options are supported for all methods, except osrm.tile.

Option	Values	Description
coordinates	array of coordinate elements: [{coordinate}, ...]	The coordinates this request will use.
bearings	array of bearing elements: [{bearing}, ...]	Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
radiuses	array of radius elements: [{radius}, ...]	Limits the search to given radius in meters.
hints	array of hint elements: [{hint}, ...]	Hint to derive position in street network.

Where the elements follow the following format:

Element	Values
coordinate	array with [{lon},{lat}] values, in decimal degrees
bearing	null or array with [{value},{range}] integer 0 .. 360,integer 0 .. 180
radius	null or double >= 0 or unlimited (default)
hint	Base64 string

All array need to have the same length as the provided coordinates array or undefined.

Examples

Query on Berlin with three coordinates:

var osrm = new OSRM('berlin.osrm');
osrm.route({
  coordinates: [[13.388860,52.517037], [13.397634,52.529407], [13.428555,52.523219]],
  overview: false
}, (err, result) => {});

OSRM Constructor

Function

new OSRM()

Creates a new OSRM object and tried to load the data from shared memory.

new OSRM('input_data.osrm')

Creats a new OSRM object from a file.

new OSRM(options)

Creates a new OSRM object where options can have one of the following keys:

Option	Values	Description
shared_memory	true (default), false	Use shared memory loaded with osmr-datastore
path	undefined (default), string	Path to file to use instead of shared memory. Requires shared_memory = false

OSRM.nearest

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

Function

OSRM.nearest(options, callback)

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

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

Option	Values	Description
number	integer >= 1 (default 1)	Number of nearest segments that should be returned.

Response

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

Examples

Querying nearest three snapped locations of 13.388860,52.517037 with a bearing between 20° - 340°.

var osrm = new OSRM('berlin.osrm');
osrm.nearest({ coordinates: [[13.388860,52.517037]], number: 3, bearings: [[0,20]]}, (err, result) => {});

OSRM.route

Returns the fastest route between two or more coordinates while visiting the waypoints in order.

Function

OSRM.route(options, callback)

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

Option	Values	Description
alternatives	true, false (default)	Search for alternative routes and return as well.*
steps	true, false (default)	Return route steps for each route leg
geometries	polyline (default), geojson	Returned route geometry format (influences overview and per step)
overview	simplified (default), full, false	Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
continue_straight	null (default), true, false	Forces the route to keep going straight at waypoints and don't do a uturn even if it would be faster. Default value depends on the profile.

* Please note that even if an alternative route is requested, a result cannot be guaranteed.

Response

• waypoints: Array of Waypoint objects representing all waypoints in order:
• routes: An array of Route objects, ordered by descending recommendation rank.

OSRM.table

Computes duration tables for the given locations. Allows for both symmetric and asymmetric tables.

Function

OSRM.table(options, callback)

Options

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

Option	Values	Description
sources	array of index elements: [{index} ...]	Use location with given index as source. Default is to use all.
destinations	array of index elements: [{index} ...]	Use location with given index as destination. Default is to use all.

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

Element	Values
index	0 <= integer < #coordinates

Response

• 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.
• sources array of Waypoint objects describing all sources in order
• destinations array of Waypoint objects describing all destinations in order

Examples

Returns a 3x3 matrix:

var osrm = new OSRM('berlin.osrm');
osrm.table({coordinates: [[13.388860,52.517037], [13.397634,52.529407], [13.428555,52.523219]]}, (err, result) => {});

Returns a 1x3 matrix:

var osrm = new OSRM('berlin.osrm');
osrm.table({coordinates: [[13.388860,52.517037], [13.397634,52.529407], [13.428555,52.523219]], sources:[0]}, (err, result) => {});

Service match

Map matching matches 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.

Function

OSRM.match(options, callback)

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

Option	Values	Description
steps	true, false (default)	Return route steps for each route
geometries	polyline (default), geojson	Returned route geometry format (influences overview and per step)
overview	simplified (default), full, false	Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
timestamps	array of timestamp elements: `[{timestamp}, ...]	Timestamp of the input location.
radiuses	array of radius elements: [{radius}, ...]	Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy.

Element	Values
timestamp	integer UNIX-like timestamp
radius	double >= 0 (default 5m)

Response

• tracepoints: Array of Ẁaypoint 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.
• 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.

OSRM.trip

The trip plugin solves the Traveling Salesman Problem using a greedy heuristic (farthest-insertion algorithm). The returned path does not have to be the shortest path, as TSP is NP-hard it is only an approximation. Note that if the input coordinates can not be joined by a single trip (e.g. the coordinates are on several disconnected islands) multiple trips for each connected component are returned.

Function

osrm.trip(options, callback)

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

Option	Values	Description
steps	true, false (default)	Return route instructions for each trip
geometries	polyline (default), geojson	Returned route geometry format (influences overview and per step)
overview	simplified (default), full, false	Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.

Response

• 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.

Result objects

Route

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 field for a parameter documentation.

  overview	Description
  simplified	Geometry is simplified according to the highest zoom level it can still be displayed on full.
  full	Geometry is not simplified.
  false	Geometry is not added.

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

Example

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

{
  distance: 90.,
  duration: 300.,
  geometry: {type: LineString, coordinates: [[120., 10.], [120.1, 10.], [120.2, 10.], [120.3, 10.]]},
  legs: [
    {
      distance: 30.,
      duration: 100,
      steps: []
    },
    {
      distance: 60.,
      duration: 200,
      steps: []
    }
  ]
}

RouteLeg

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.

• summary: Summary of the route taken as string. Depends on the steps parameter:

  steps
  true	Names of the two major roads used. Can be empty if route is too short.
  false	empty string

• steps: Depends on the steps parameter.

  steps
  true	array of RouteStep objects describing the turn-by-turn instructions
  false	empty array

Example

With steps=false:

{
  distance: 30.,
  duration: 100,
  steps: []
}

RouteStep

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.

  geometries
  polyline	polyline with precision 5 in [latitude,longitude] encoding
  geojson	GeoJSON LineString or GeoJSON Point if it is only one coordinate (not wrapped by a GeoJSON feature)

• name: The name of the way along which travel proceeds.

• mode: A string signifying the mode of transportation.

• maneuver: A StepManeuver object representing the maneuver.

Example

StepManeuver

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.

• bearing_after: The clockwise angle from true north to the direction of travel immediately after the maneuver.

• type A string indicating the type of maneuver

  type	Description
  turn	a basic turn into direction of the modifier
  new name	no turn is taken, but the road name changes
  depart	indicates the departure of the leg
  arrive	indicates the destination of the leg
  merge	merge onto a street (e.g. getting on the highway from a ramp
  ramp	take a ramp to exit a highway
  fork	take the left/right side at a fork depending on modifier
  end of road	road ends in a T intersection turn in direction of modifier
  continue	Turn in direction of modifier to stay on the same road
  roundabout	traverse roundabout, has additional field exit with NR if the roundabout is left.
  rotary	a larger version of a roundabout, can offer rotary_name in addition to the exit parameter.
  notification	not an actual turn but a change in the driving conditions. For example the travel mode.

  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.

  modifier	Description
  uturn	indicates reversal of direction
  sharp right	a sharp right turn
  right	a normal turn to the right
  slight right	a slight turn to the right
  straight	no relevant change in direction
  slight left	a slight turn to the left
  left	a normal turn to the left
  sharp left	a sharp turn to the left

  The meaning depends on the type field.

  type	Description
  turn	modifier indicates the change in direction accomplished through the turn
  depart/arrive	modifier indicates the position of departure point and arrival point in relation to the current direction of travel

• exit An optional integer indicating number of the exit to take. The field exists for the following type field:

  type	Description
  roundabout	Number of the roundabout exit to take. If exit is undefined the destination is on the roundabout.
  turn or end of road	Indicates the number of intersections passed until the turn. Example instruction: at the fourth intersection, turn left

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

Waypoint

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
• 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.

OSRM.tile

This 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.

Function

osrm.tile([x, y, z], callback)

The x, y, and z 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.

Response

The result will be Buffer that contains a PBF encoded vector tile.