-
-
Notifications
You must be signed in to change notification settings - Fork 3.9k
Server api
OSRM (partially) implements HTTP 1.1 and serves queries much like normal web servers do.
OSRM features three services currently. These are:
- Location of a nearest node of the road network to a given coordinate (locate).
- Location of a nearest point on any street segment of the road network for a given coordinate. (nearest)
- Computation of a shortest path on the road network between two coordinates given an ordered list of via points (viaroute).
- Computation of distance tables. Given a list of locations a matrix is returned containing the travel time for all combinations of trips.
The general layout of a query is much like query strings for http. Once OSRM is started it listens for incoming connections. Let's assume a server called server listens on port 5000.
Then any service can be queried through
http://server:5000/_service_?param1=value¶m2=value&...¶mX=value
Locating points on the road network can be done either by using the command nearest or locate. If you are unsure whether to use the nearest or the locate service, then rule of thumb says you should use nearest.
The nearest neighbor locationing relies on an external memory data structure on the hard drive. To keep the number of disk accesses low, it searches only a limited area around the input coordinate.
A nearest node point is queried by sending a request formatted as follows:
where lat and lon are latitude and longitude of the respective coordinate. For example, the following query will ask for the closest node to a certain location in Berlin, Germany:
The answer that is returned looks like this:
{
"status": 0,
"mapped_coordinate": [
52.41427,
13.32626
]
}A nearest point on a street segment is queried by sending a request formatted as follows:
where lat and lon are latitude and longitude of the respective coordinate. For example, the following query will ask for a closest point on any street segment to a certain location in Berlin, Germany:
The answer that is returned looks like this:
{
"status": 0,
"mapped_coordinate": [
52.42259,
13.33383
],
"name": "Mariannenstraße"
}Using the syntax above, the answer comes formatted as JSON, which can be further processed by many programming languages without much further ado. The output can also be formatted as JSONP, e.g.
http://server:5000/nearest?loc=52.555485441735,13.342227642887&jsonp=function
returns the JSON output wrapped by function(), which is easily processable by Javascript:
function({"status":0,"result":[52.55567, 13.34252]"})
The jsonp parameter works for nearest, locate and timestamp.
Basic point to point queries between the coordinates (lat1,lon1) and (lat2,lon2) are requested like this:
http://server:5000/viaroute?loc=_lat1_,_lon1_&loc=_lat2_,_lon2_
To route via certain coordinates list them in the query string in the order of appearance (currently limited to 25 max points):
Be sure, not to actually put three dots '...' in the query string, but one '&loc=lat,lon' per via coordinate.
The output is formatted as JSON. In this example, the route Germany and has no via points besides start and destination.
{
"status": 0,
"status_message": "Found route between points",
"route_geometry": "_lbw~A}}ijOzSe~@vMc_@eYe]qEcFaFoD}GqBmTqBgEyBuCiF{JeX_KgUyUq\\eo@ueA}G{MXqBc@iFuAkBv@}EbL}R|oBc}C",
"route_instructions": [
[
"10",
"Schulstraße",
126,
0,
18,
"126m",
"SE",
116
],
[
"7",
"Am Rahmtor",
57,
2,
11,
"57m",
"NE",
38
],
[
"1",
"Marktplatz",
94,
3,
17,
"94m",
"NE",
35
],
[
"2",
"Eppsteiner Straße",
274,
8,
50,
"274m",
"NE",
45
],
[
"11-2",
"Feldbergstraße",
310,
17,
29,
"310m",
"E",
112
],
[
"15",
"",
0,
20,
0,
"",
"N",
0
]
],
"route_summary": {
"total_distance": 883,
"total_time": 135,
"start_point": "Marienstraße",
"end_point": "Feldbergstraße"
},
"alternative_geometries": [
"_lbw~A}}ijO~UhSrLnF~Ocs@bGg\\nIuRpi@weA~cAknBdEoGqs@kbC{B_L}]ktAcDeW]aLoDuQcLaa@gQus@ke@ds@yl@|`A"
],
"alternative_instructions": [
[
[
"10",
"Marienstraße",
72,
0,
11,
"72m",
"SW",
209
],
[
"7",
"Altkönigstraße",
66,
2,
12,
"66m",
"SE",
116
],
[
"1",
"K 772",
701,
3,
82,
"701m",
"SE",
117
],
[
"1",
"Liebfrauenstraße",
151,
12,
19,
"151m",
"E",
84
],
[
"7",
"Feldbergstraße",
201,
16,
22,
"201m",
"NW",
319
],
[
"15",
"",
0,
18,
0,
"",
"N",
0
]
]
],
"alternative_summaries": [
{
"total_distance": 1194,
"total_time": 148,
"start_point": "Marienstraße",
"end_point": "Feldbergstraße"
}
],
"route_name": [
"Eppsteiner Straße",
"Feldbergstraße"
],
"alternative_names": [
[
"K 772",
"Feldbergstraße"
]
],
"via_points": [
[
50.20232,
8.574447
],
[
50.202712,
8.582738
]
],
"via_indices": [
0,
51
],
"alternative_indices": [
0,
45
]
}The geometry of the route is transferred in encoded form. See here for a definition of the format. The route geometry is compressed with a precision of six digits. See here for a proper JavaScript implementation.
Driving directions are given as integer numbers as defined in the source file data_structures/turn_instructions.hpp.
All the fields are described in Output Json
If alternatives are requested (alt=true), following arrays may contain elements, one for each alternate route: alternative_geometries: array of route_geometry alternative_instructions: array of route_instructions alternative_summaries: Array of route_summary alternative_names: Array of route_name
A number of additional parameters can be appended to the query:
-
&z={0,...,18}specifies the zoom level and compresses the route geometry accordingly. Low zoom levels will also cause OSRM to ignore small isolated islands when picking the start/end location. The default value is 18, which implies that when it is not specified in the query result may not found any road cause of using small unconnected part. -
&output={json, gpx}format the output as JSON or GPX. [Default: JSON] -
&jsonp=_function_See Additional parameters (JSONP) -
&instructions={true, false}Return route instructions for each route [Default: false] -
&alt={true, false}Return an alternative route [Default: true] -
&geometry={true, false}Return route geometry [Default: true]
Requesting distance tables is very similar to requesting a route. The general layout of a distance table query is the following:
Consider the following example:
gives the following resulting table:
{
"distance_table": [
[
0,
26084,
22942,
26989
],
[
26319,
0,
30810,
19607
],
[
22782,
30482,
0,
37495
],
[
27376,
19415,
37693,
0
]
]
}The results are network distance, i.e. travel-time, in 10th of seconds.
Example:
{
"matchings":
[
{
"matched_points":[[52.542648,13.393252], [52.543056,13.394707], [52.542107,13.397389]],
"indices": [0, 1, 2],
"geometry": "oj}ecBgumpXuX{yA@A|tAccAoYobB"
}
]
}As noted at the top of this page, OSRM only partially implements HTTP 1.1. Notably absent is support for pipelining, which allows multiple requests to be served over a single socket. OSRM Issue #531 has some documented workarounds.
You are welcome to query our server for routes, if you adhere to the [API Usage Policy](API Usage Policy).