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/7.42056,43.731142;7.42462,43.73848?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/7.42056,43.731142;7.42462,43.73848?alternatives=true&overview=full&geometries=polyline&steps=true&annotations=duration,distance&skip_waypoints=true"Response Example
{
"code": "Ok",
"routes": [
{
"legs": [
{
"steps": [],
"weight": 156.6,
"summary": "",
"duration": 156.6,
"distance": 1455.8
}
],
"weight_name": "routability",
"geometry": "ki|iG_hhl@YyAo@qC[oAO]EKGMIIKGGCGCI?G?I@E@KDIDKHSTOLGFQJGBQ@QJODKDUDA@A?EBYHUHKBE@IBC@YH[HKBE@C?I@C@C?A@M@I@KBC?I@I@K@OBK@I?e@BG@Q@I@G?M?M@G?K?Q?IAa@AA?MCOAOEKCKCUISGg@e@KI?CAACEEAEGACGKESEa@IuACk@ACCWGm@OgACUACCUKu@Ee@C_@Ci@AWAc@AMCMAKIWYiAEQEQESCOESEg@Gi@Ig@CICICGCECECCEECCECCACCE?EAE?E@E?GBC@EDEBCDEHGJWj@M\\KTQ^KRBBB@l@n@BBDHCJm@hD?JALJDn@Z?@",
"weight": 156.6,
"duration": 156.6,
"distance": 1455.8
}
]
}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