Calculate car/driving routes
Calculate driving routes between coordinates through the full-planet OSRM car service. This shared service is independent of the selected BusMaps or WikiRoutes transit data host and is available with either capi-host value. Query parameters are forwarded to the OSRM route service without changing the response contract.
Response fields and units
| Field | Format / unit | Meaning |
|---|---|---|
routes[].distance, routes[].legs[].distance, routes[].legs[].steps[].distance | meters | Route, leg and step distance |
routes[].duration, routes[].legs[].duration, routes[].legs[].steps[].duration | seconds | Route, leg and step duration |
routes[].legs[].annotation.distance[], routes[].legs[].annotation.duration[] | meters, seconds | Per-segment distance and duration |
waypoints[].distance | meters | Distance from the input coordinate to the snapped road waypoint |
waypoints[].location, GeoJSON coordinates | [longitude, latitude] in decimal degrees | Coordinate-array order |
routes[].weight | unit named by weight_name | Routing weight |
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
alternatives | boolean or integer | No | Return alternative routes; an integer limits their number | true |
overview | string | No | Geometry overview detail level | full |
geometries | string | No | Geometry format | polyline |
steps | boolean | No | Include turn-by-turn driving instructions | true |
annotations | string | No | Comma-separated route annotations to include | duration,distance |
skip_waypoints | boolean | No | Omit waypoint details from the response | true |
Try It Out
Common usage with optional parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/car/route/-0.142410,51.539270;-0.128030,51.507340?alternatives=true&overview=full&skip_waypoints=true"Popular parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/car/route/-0.142410,51.539270;-0.128030,51.507340?alternatives=true&overview=full&geometries=polyline&steps=true&annotations=duration,distance&skip_waypoints=true"Response Example
{
"code": "Ok",
"routes": [
{
"legs": [
{
"steps": [],
"weight": 803.8,
"summary": "",
"duration": 795.8,
"distance": 5015.6
}
],
"weight_name": "routability",
"geometry": "mgqyH`yZO?KA}@Me@Gg@Ge@GUAy@Gg@EGAI?MCICEBIAM?]EQAEGAAG?a@EKAOA@MLs@BOPaABIDY@G@C?E?G@SPODEFEDEJCDEJI`@[HGNMJIr@i@BC@AFE@ALKJKFEjB}ATSh@e@LKRODELKHGFEZWPOZWFGPOl@g@DCLKJKh@c@fBwAFG`@a@l@a@h@_@DENMHGr@k@tAeAPOFEt@m@v@o@DEDAPEL?R@H@??H?vA?F?D@HFJHPNJFp@f@z@n@FJVh@f@lAFHFLDJ@@JTDGFJBF@DPb@Xz@DNH\\DP@T@B@NBVBZ?TFn@BZBLDLBFDDDBD@B?D?NCJABAD?FADEBAFATEHAZIPErA[PEB?PGr@OTALA\\AFAHJZAj@CJA~@CDEl@?H?D?B????@@@?@@@X@L?J?HAN?V?H???L?J?`@?H?F?F?N?J?P@DAV?J@L?L?H?R?R?L?HAP?B?@?v@?Z?J?L?@?B?DAH?J?@?F?L?r@ADAH?HAJAHCLCDAj@UFWFEFE\\Q^U@MBm@?G@K?I@IAUAOCMGSMe@Og@CKU}@GYEW?CCM?CAQ?E?G@IDEBEHI@An@q@BERULO^a@HKDELMHIBEBCVYFGHIBEl@q@DCBCBCDEHI@CBCFGdFwFNQ@ADEFIJKLO@AFILO`CkCTWFI??LMHK@CDEJK|AeBx@_ADE@C@?@C@AJKHK@ABCDE^a@r@u@FIHKLMHIBEDEJKf@k@hAoAFGdAkAVYLORWLMNONORQFGFEHELKBAHGFE@Az@o@b@]NOHG@?BCLKFGBA@ABC@ABCTQZUZYDEFEDCBA@AD?B@RFj@V@@B@@@D@FDDBLH@B@@DFDF@?DBB@B@B@??@@RDNDTDFBFBFDHDDAFFB@BB@JNNNPDDBB|@`A@@JLDDBBHJt@~@V^NTNP\\h@JLJN@@@BBBDFPTVMJGHEXOFCJGPIDCFCZOt@a@HEJEPELCB?LAXAF?P@R?@?J@T?P?F?H@\\?B@N?b@AZ?FAVEPCJEPI^SXU@AZa@JSP_@FQBEDIBGDELIJCFAFA@ARANCTCN?REH?HAN?D?JAPAn@KPEJCFAFAVCHBF@D@JLHFJJHJ??B?F@F@DBDBHL@HBHBJDR@L?DAFCNEHKLA@E@C?",
"weight": 803.8,
"duration": 795.8,
"distance": 5015.6
}
]
}Response Schema
View JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Car Route Response",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "OSRM response code"
},
"waypoints": {
"type": "array",
"items": {
"type": "object",
"properties": {
"location": {
"type": "array",
"items": {
"type": "number"
},
"description": "Point location. Coordinate arrays use [longitude, latitude] in decimal degrees; objects expose named latitude/longitude fields"
},
"hint": {
"type": "string",
"description": "Opaque OSRM hint for re-snapping the waypoint"
},
"distance": {
"type": "number",
"description": "Distance in meters"
},
"name": {
"type": "string",
"description": "Display name"
}
},
"required": [
"location",
"hint",
"name",
"distance"
]
},
"description": "Snapped input waypoints"
},
"routes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"duration": {
"type": "number",
"description": "Duration in seconds"
},
"legs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"duration": {
"type": "number",
"description": "Duration in seconds"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"intersections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"classes": {
"type": "array",
"items": {
"type": "string"
}
},
"location": {
"type": "array",
"items": {
"type": "number"
},
"description": "Point location. Coordinate arrays use [longitude, latitude] in decimal degrees; objects expose named latitude/longitude fields"
},
"bearings": {
"type": "array",
"items": {
"type": "integer"
},
"description": "Available bearings at the intersection (degrees)"
},
"in": {
"type": "integer",
"description": "Index of the incoming bearing"
},
"entry": {
"type": "array",
"items": {
"type": "boolean"
},
"description": "Whether each bearing is a permitted entry"
},
"out": {
"type": "integer",
"description": "Index of the outgoing bearing"
}
},
"required": [
"entry",
"bearings",
"location"
]
},
"description": "Intersections passed in this step"
},
"duration": {
"type": [
"number",
"integer"
],
"description": "Duration in seconds"
},
"driving_side": {
"type": "string",
"description": "Driving side at the step (left/right)"
},
"geometry": {
"type": "object",
"properties": {
"coordinates": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
}
},
"description": "Coordinate pair in [longitude, latitude] order, in decimal degrees"
},
"type": {
"type": "string",
"description": "Type discriminator for the object"
}
},
"required": [
"coordinates",
"type"
],
"description": "Route geometry in the requested format"
},
"weight": {
"type": [
"number",
"integer"
],
"description": "Routing weight"
},
"distance": {
"type": [
"number",
"integer"
],
"description": "Distance in meters"
},
"name": {
"type": "string",
"description": "Display name"
},
"maneuver": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Type discriminator for the object"
},
"location": {
"type": "array",
"items": {
"type": "number"
},
"description": "Point location. Coordinate arrays use [longitude, latitude] in decimal degrees; objects expose named latitude/longitude fields"
},
"exit": {
"type": "integer"
},
"bearing_before": {
"type": "integer",
"description": "Bearing before the maneuver (degrees)"
},
"bearing_after": {
"type": "integer",
"description": "Bearing after the maneuver (degrees)"
},
"modifier": {
"type": "string",
"description": "Direction modifier of the maneuver (left, right, ...)"
}
},
"required": [
"type",
"location",
"bearing_before",
"bearing_after",
"modifier"
],
"description": "Turn maneuver for this step"
},
"mode": {
"type": "string",
"description": "Driving mode reported by OSRM for this route step"
}
},
"required": [
"intersections",
"duration",
"driving_side",
"geometry",
"weight",
"distance",
"name",
"maneuver",
"mode"
]
},
"description": "Turn-by-turn driving instructions"
},
"annotation": {
"type": "object",
"properties": {
"distance": {
"type": "array",
"items": {
"type": "number"
},
"description": "Distance in meters"
},
"duration": {
"type": "array",
"items": {
"type": [
"number",
"integer"
]
},
"description": "Duration in seconds"
}
},
"required": [
"distance",
"duration"
],
"description": "Requested per-segment annotations"
},
"weight": {
"type": "number",
"description": "Routing weight"
},
"distance": {
"type": "number",
"description": "Distance in meters"
},
"summary": {
"type": "string",
"description": "Summary of the leg (main streets)"
}
},
"required": [
"weight",
"duration",
"steps",
"distance"
]
},
"description": "Route legs between consecutive waypoints"
},
"geometry": {
"type": [
"object",
"string"
],
"description": "Route geometry in the requested format"
},
"weight": {
"type": "number",
"description": "Routing weight"
},
"distance": {
"type": "number",
"description": "Distance in meters"
},
"weight_name": {
"type": "string",
"description": "Routing weight metric"
}
},
"required": [
"duration",
"legs",
"geometry",
"distance",
"weight",
"weight_name"
]
},
"description": "Calculated driving routes"
},
"message": {
"type": "string",
"description": "Error detail when the route cannot be calculated"
}
},
"required": [
"routes",
"code"
]
}Response Codes
200
OSRM route response returned successfully400
Invalid coordinates, request parameters, or no routable segment500
Car routing service is unavailable