Server api

Server API

The HTTP interface provided by osrm-routed (partially) implements HTTP 1.1 and serves queries much like normal web servers do.

The general structure of all queries looks like this:

http://{server address}/{service}?{parameter}={value}

Example:

http://127.0.0.1:5000/locate?loc=52.4224,13.333086

The response is returned as JSON object by default. If you call from within Javascript and want to specify a callback function that should be called use the jsonp={callback name} parameter.

Each response has the following general structure:

{
  status: 0,
  status_message: "Message text",
  .....
}

• status the status code. 0 means successful, 207 means no route was found.
• status_message (optional) can either be Found route between points or Cannot find route between points

Available Services

Each service is implemented as a plugin for OSRM. Currently the following services are available:

Service	Description
viaroute	shortest path between given coordinates
nearest	returns the nearest street segment for a given coordinate
locate	returns coordinate snapped to nearest node
table	computes distance tables for given coordinates
match	matches given coordinates to the road network

Service: locate

Query

http://{server}/locate?loc={lat,lon}

Parameter	Description
loc	Location of the node as latitude longitude pair separated by a comma

Response

• mapped_coordinate Array that contains the [lat, lon] pair of the snapped coordinate

Example

Query

http://router.project-osrm.org/locate?loc=52.4224,13.333086

Response:

{
    "status": 0,
    "mapped_coordinate": [
        52.41427,
        13.32626
    ]
}

Service nearest

Query

http://{server}/nearest?loc={lat,lon}

Parameter	Description
loc	Location of the node as latitude longitude pair separated by a comma

Response

• name Name of the street the coordinate snapped to
• mapped_coordinate Array that contains the [lat, lon] pair of the snapped coordinate

Example

Query

http://router.project-osrm.org/nearest?loc=52.4224,13.333086

Response:

{
    "status": 0,
    "mapped_coordinate": [
        52.42259,
        13.33383
    ],
    "name": "Mariannenstraße"
}

Service viaroute

This service provides shortest path queries with multiple via locations. It supports the computation of alternative paths as well as giving turn instructions.

Query

http://{server}/viaroute?loc={lat,lon}&loc={lat,lon}<&loc={lat,lon} ...>

Parameter	Values	Description
loc	lat,lon	Location of the via point
locs	Encoded polyline	Location of the via point encoded as polyline
z	0 ... 18 (default)	Zoom level used for compressing the route geometry accordingly
output	json (default), gpx	Format of the response
instructions	true, false (default)	Return route instructions for each route
alt	true (default), false	Return an alternative route
geometry	true (default), false	Return route geometry

Response

• route_geometry Geometry of the route compressed as polyline, but with 6 decimals. You can use the npm module polyline to decompress it.
• route_instructions Array containing the instructions for each route segment. Each entry is an array of the following form: [{drive instruction code}, {street name}, {length}, {location index}, {time}, {formated length}, {direction}, {azimuth}]
  • driving directions code integer numbers as defined in the source file turn_instructions.hpp.
  • street name name of the street as string
  • length length of the street in meters as integer
  • position index to the list of coordinates represented by the decoded route_geometry as integer
  • time travel time in seconds as float
  • formated length length with unit as string
  • direction abbreviation N: north, S: south, E: east, W: west, NW: North West, ... as string
  • azimuth as float
  • mode of transportation as defined in the profile as integer (usually 1 means the default mode, e.g. 'car' for the car profile, 'bike' for the bicycle profile etc.)
• route_summary
  • total_distance total length in meters as integer
  • total_time total trip time in seconds as integer
  • start_point name of the first street as string
  • end_point name of the last street as string
• route_name name of the route ("most prominent streets") as array of string
• via_indices index to the list of coordinates represented by the decoded route_geometry as integer
• via_points array of via points, each via point is an array of coordinates: [lat, lon]
• hint_data this can be used to speed up incremental queries, where only a few via change
  • checksum pass this with the next requests
  • locations array of hints for each vis point append with use the hint parameter to pass it after the corresponding loc
• found_alternative true or false

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

Example

Query

http://router.project-osrm.org/viaroute?loc=52.503033,13.420526&loc=52.516582,13.429290&instructions=true

Response:

{
    "alternative_geometries": [
        "q~occB{}brX}KaHyY{QaW}OoN{IoHuEcIcFeM}HoKyGuBsA}U}OcvA}}@yxBgwAgT`kAyAjH_CvLyDvS{Mhv@aDbS{E`VkY{QofAur@eTkN{QsLkFcF_b@q\\_IqImKkJwNyMaGqFwD{KeEkGad@aq@eReTyPgOk_A_z@fE_q@^_GnIqkAkTeGcg@oMgCq@"
    ],
    "alternative_indices": [
        0,
        42
    ],
    "alternative_instructions": [
        [
            [
                "10",
                "Adalbertstra\u00dfe",
                701,
                0,
                71,
                "701m",
                "NE",
                23,
                1
            ],
            [
                "7",
                "L 1066",
                260,
                12,
                21,
                "260m",
                "NW",
                295,
                1
            ],
            [
                "3",
                "Michaelkirchstra\u00dfe",
                283,
                19,
                20,
                "283m",
                "NE",
                23,
                1
            ],
            [
                "1",
                "Michaelbr\u00fccke",
                70,
                24,
                5,
                "70m",
                "NE",
                27,
                1
            ],
            [
                "1",
                "An der Michaelbr\u00fccke",
                95,
                25,
                9,
                "95m",
                "NE",
                33,
                1
            ],
            [
                "2",
                "Lichtenberger Stra\u00dfe",
                326,
                29,
                23,
                "325m",
                "NE",
                54,
                1
            ],
            [
                "3",
                "Singerstra\u00dfe",
                149,
                35,
                15,
                "149m",
                "E",
                102,
                1
            ],
            [
                "7",
                "Krautstra\u00dfe",
                120,
                38,
                12,
                "120m",
                "N",
                13,
                1
            ],
            [
                "15",
                "",
                0,
                41,
                0,
                "0m",
                "N",
                0
            ]
        ]
    ],
    "alternative_names": [
        [
            "Adalbertstra\u00dfe",
            "Lichtenberger Stra\u00dfe"
        ]
    ],
    "alternative_summaries": [
        {
            "end_point": "Krautstra\u00dfe",
            "start_point": "Adalbertstra\u00dfe",
            "total_distance": 2005,
            "total_time": 169
        }
    ],
    "found_alternative": true,
    "hint_data": {
        "checksum": 2307491829,
        "locations": [
            "27oZAOC6GQCMVAAAEQAAAEIAAAAAAAAAAAAAAP____8AAAAA-SEhA-7HzAAAABEA",
            "TJm4A1Xa4QYIcgEABwAAAAgAAAA2AAAAAAAAADBB-QMAAAAA5lYhAyrqzAABABEA"
        ]
    },
    "route_geometry": "q~occB{}brX}KaHyY{QaW}OoN{IoHuEcIcFeM}HoKyGuBsAZ}Ip@aUXaZIqT_@sUi@kNgCk`@wAePsCwTwDuTsG}YwIsZgFuMmB_F_HmQ}NoVgFyGoCsDmK}KgLaJuHeEgEyCiHcFuEeDwFGmIKoQW{JwBwHeFmFmDePcNuJqIwBmBug@}c@yE}Dk]gYsPeImg@{MoJgCw`@sK_Ck@ot@qPkBg@_D{@cHgBeR}E{\\yIm_@}JuEeAiGaBuBi@eMcDuPkE{Djo@{@jMaCp_@eKt_BkTeGcg@oMgCq@",
    "route_instructions": [
        [
            "10",
            "Adalbertstra\u00dfe",
            251,
            0,
            26,
            "250m",
            "NE",
            23,
            1
        ],
        [
            "3",
            "Bethaniendamm",
            719,
            9,
            53,
            "719m",
            "E",
            99,
            1
        ],
        [
            "1",
            "Schillingbr\u00fccke",
            90,
            41,
            6,
            "90m",
            "NE",
            27,
            1
        ],
        [
            "1",
            "An der Schillingbr\u00fccke",
            108,
            43,
            12,
            "108m",
            "NE",
            28,
            1
        ],
        [
            "1",
            "Andreasstra\u00dfe",
            533,
            46,
            40,
            "532m",
            "N",
            13,
            1
        ],
        [
            "7",
            "Singerstra\u00dfe",
            212,
            62,
            22,
            "212m",
            "W",
            281,
            1
        ],
        [
            "3",
            "Krautstra\u00dfe",
            120,
            66,
            12,
            "120m",
            "N",
            13,
            1
        ],
        [
            "15",
            "",
            0,
            69,
            0,
            "0m",
            "N",
            0
        ]
    ],
    "route_name": [
        "Bethaniendamm",
        "Andreasstra\u00dfe"
    ],
    "route_summary": {
        "end_point": "Krautstra\u00dfe",
        "start_point": "Adalbertstra\u00dfe",
        "total_distance": 2034,
        "total_time": 164
    },
    "status": 0,
    "status_message": "Found route between points",
    "via_indices": [
        0,
        70
    ],
    "via_points": [
        [
            52.503033,
            13.420526
        ],
        [
            52.516582,
            13.42929
        ]
    ]
}

Service table

This computes distance tables for the given via points. Currently all pair-wise distances are computed. Please note that the distance in this case is the travel time which is the default metric used by OSRM.

Query

http://{server}/table?loc={lat,lon}&loc={lat,lon}<&loc={lat,lon} ...>

Parameter	Values	Description
loc	lat,lon	Location of the via point

Response

• distance_table array of arrays that stores the matrix in row-major order. distance_table[i][j] gives the travel time from the i-th via to the j-th via point. Values are given in 10th of a second.

Example

http://router.project-osrm.org/table?loc=52.554070,13.160621&loc=52.431272,13.720654&loc=52.554070,13.720654&loc=52.554070,13.160621

{
    "distance_table": [
        [
            0,
            31089,
            31224,
            0
        ],
        [
            31248,
            0,
            13138,
            31248
        ],
        [
            31167,
            13188,
            0,
            31167
        ],
        [
            0,
            31089,
            31224,
            0
        ]
    ]
}

Service match

Map matching matches given GPS points to the road network in the most plausible way. Currently the algorithm works best with trace data that has a sample resolution of 5-10 samples/min. 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. The indices array contains the indices of the input location that could be matched.

Query

http://{server}/match?loc={lat,lon}&t={timestamp}&loc={lat,lon}&t={timestamp}<&loc={lat,lon}&t={timestamp} ...>

Parameter	Values	Description
loc	lat,lon	Location of the point
locs	Encoded polyline	Location of the via point encoded as polyline
t	UNIX-like timestamp	Timestamp of the preceding point
geometry	true (default), false	Return route geometry
compression	true (default), false	Compress route geometry as a polyline; geometry is a list of [lat, lng] pairs if false
classify	true, false (default)	Return a confidence value for this matching
instructions	true, false (default)	Return the instructions of the matched route, which each matched point as via.
gps_precision	float value (default: 5)	Specify gps precision as standart deviation in meters. See [1]
matching_beta	float value (default: 10)	Specify beta value for matching algorithm. See [1]

Response

• matchings array containing an object for each partial sub-matching of the trace.
  • matched_points coordinates of the points snapped to the road network in [lat, lon]
  • indices array that gives the indices of the matched coordinates in the original trace
  • geometry geometry of the matched trace in the road network. If compression is true (the default), the geometry is compressed as polyline, but with 6 decimals. You can use the npm module polyline to decompress it
  • confidence value between 0 and 1, where 1 is very confident. Please note that the correctness of this value depends highly on the assumptions about the sample rate mentioned above.
  • instructions see route_instructions of the viaroute service.

Example

https://router.project-osrm.org/match?loc=52.542648,13.393252&t=1424684612loc=52.543079,13.394780&t=1424684616&loc=52.542107,13.397389&t=1424684620

{
   "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"
     }
   ]
}

[1] "Hidden Markov Map Matching Through Noise and Sparseness"; P. Newson and J. Krumm; 2009; ACM.

HTTP Pipelining

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.

Public API usage policy

You are welcome to query our server for routes, if you adhere to the [API Usage Policy](API Usage Policy).