-
Notifications
You must be signed in to change notification settings - Fork 1
Server api
OSRM (partially) implements http 1.1 and serves queries much like normal web servers do.
OSRM features three services currenty. 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).
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.
The 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 neareast 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 harddrive. 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:
{
"version": 0.3,
"status": 0,
"mapped_coordinate": [
52.41427,
13.32626
],
"transactionId": "OSRM Routing Engine JSON Locate (v0.3)"
}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:
{
"version": 0.3,
"status": 0,
"mapped_coordinate": [
52.42259,
13.33383
],
"name": "Mariannenstraße",
"transactionId": "OSRM Routing Engine JSON Nearest (v0.3)"
}Using the syntax above, the answer comes formatted as JSON, which can be further processed by many programming languages without much futher ado. The output can also be formatted as JSONP, e.g.
http://server:5000/nearest?52.555485441735&13.342227642887&jsonp=function
returns the JSON output wrapped by function(), which is easily processable by Javascript:
function({"version":0.3,"status":0,"result":[52.55567, 13.34252],"transactionId": "OSRM Routing Engine JSON Nearest (v0.3)"})
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:
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.
{
"version": 0.3,
"status": 0,
"status_message": "Found route between points",
"route_geometry": "galqHisis@gA}@pBsHuAaB}CgAyI_P@IKa@tDoG",
"route_instructions": [
[
"10",
"Marienstraße",
45,
0,
2,
"45m",
"NE",
319.32
],
[
"3",
"Schulstraße",
125,
1,
181,
"125m",
"E",
251.9
],
[
"7",
"Am Rahmtor",
58,
2,
70,
"58m",
"NE",
311.24
],
[
"1",
"Marktplatz",
90,
3,
109,
"90m",
"NE",
315.05
],
[
"2",
"Eppsteiner Straße",
267,
4,
321,
"267m",
"NE",
302.52
],
[
"11-2",
"Feldbergstraße",
137,
7,
3,
"137m",
"E",
254.71
],
[
"15",
"",
0,
8,
0,
"",
"N",
0
]
],
"route_summary": {
"total_distance": 740,
"total_time": 86,
"start_point": "Marienstraße",
"end_point": "Feldbergstraße"
},
"via_points": [],
"hint_data": {
"checksum": -276364421,
"locations": [
"CSIsFYgPAAACAAAA____f7-KN3qj0KE_JJpMAEUVDQA",
"GrSEAHsrAAATAAAAAQAAAFEhcqjIsu4_4JpMAAEYDQB"
]
},
"transactionId": "OSRM Routing Engine JSON Descriptor (v0.3)"
}The geometry of the route is transferred in encoded form. See here for a definition of the format.
Driving directions are given as integer numbers as defined in the source file DataStructures/TurnInstructions.h.
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
The above reply has a section hint_data. This gives (encoded) information about the true start and endpoints. If a route quere is very similar the previous one, this can give the answer faster.
Any client implementing the API is supposed to adhere to the following:
-
Append
&checksum=...to the URI where ... is the checksum in hint_data.checksum from the previous request. -
Furthermore append
&hint=...after each&loc=...parameter if it did not change from the previous request, respectively. -
If a coordinate has changed, then don't give any hint for that particular coordinate.
-
Hints have to be placed directly behind the corresponding
&loc=...parameter.
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. -
&output={json, gpx}format the output as JSON or GPX. [Default: JSON] -
&jsonp=_function_ -
&instructions={true, false}Return route instructions for each route [Default: false] -
&alt={true, false}Return an alternative route [Default: true]
You are welcome to query our server for routes, if you adhere to the [API Usage Policy](API Usage Policy).