Directions

Road geometry, distance and duration between waypoints.

directions.compute Stable call

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/directions

{
    "type": "object",
    "properties": {
        "options": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "geometry": {
                    "type": [
                        "boolean",
                        "null"
                    ]
                }
            }
        },
        "profile": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "car",
                "van",
                "truck",
                "bike",
                "foot",
                "motorcycle"
            ]
        },
        "region": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "NA",
                "EU",
                "AU",
                "ASIA",
                "na",
                "eu",
                "au",
                "asia"
            ]
        },
        "waypoints": {
            "type": "array",
            "minItems": 2,
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 128
                    },
                    "lat": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90
                    },
                    "lng": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180
                    }
                },
                "required": [
                    "lat",
                    "lng"
                ]
            }
        }
    },
    "additionalProperties": false,
    "required": [
        "waypoints"
    ]
}

Request example

{
    "waypoints": [
        {
            "id": "depot",
            "lat": 45.5017,
            "lng": -73.5673
        },
        {
            "id": "order-1001",
            "lat": 45.5088,
            "lng": -73.554
        },
        {
            "id": "order-1002",
            "lat": 45.4972,
            "lng": -73.5786
        }
    ],
    "options": {
        "geometry": true
    }
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/directions

Response schema

{
    "description": "Distance, driving time and geometry of every leg between consecutive waypoints, in the order given. A leg that cannot be routed is reported with `reachable: false` and nulls; the other legs are still answered.",
    "data": {
        "type": "object",
        "properties": {
            "legs": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "from": {
                            "type": "string",
                            "description": "Waypoint id the leg starts at."
                        },
                        "to": {
                            "type": "string",
                            "description": "Waypoint id it ends at."
                        },
                        "reachable": {
                            "type": "boolean"
                        },
                        "distance_meters": {
                            "type": [
                                "integer",
                                "null"
                            ]
                        },
                        "duration_seconds": {
                            "type": [
                                "integer",
                                "null"
                            ]
                        },
                        "geometry": {
                            "type": [
                                "string",
                                "null"
                            ],
                            "description": "Encoded polyline (precision 5). Null when `options.geometry` is false or the leg is unreachable."
                        }
                    }
                }
            },
            "totals": {
                "type": "object",
                "properties": {
                    "distance_meters": {
                        "type": "integer",
                        "description": "Sum of the reachable legs."
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "description": "Sum of the reachable legs."
                    },
                    "legs": {
                        "type": "integer"
                    },
                    "unreachable_legs": {
                        "type": "integer"
                    }
                }
            }
        }
    },
    "meta": {
        "type": "object",
        "properties": {
            "region": {
                "type": "string"
            },
            "profile": {
                "type": "string"
            },
            "geometry": {
                "type": "boolean"
            },
            "geometry_format": {
                "type": [
                    "string",
                    "null"
                ]
            },
            "mode": {
                "type": "string"
            }
        }
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "directions.compute",
    "billing": {
        "unit": "call",
        "quantity": 1,
        "counted": true,
        "breakdown": {
            "waypoints": 3,
            "legs": 2
        }
    },
    "data": {
        "legs": [
            {
                "from": "depot",
                "to": "order-1001",
                "reachable": true,
                "distance_meters": 1840,
                "duration_seconds": 245,
                "geometry": "y`vtGjr_`MJUNYL[h@gAHOFQBIHOc@g@MOa@]s@q@EGEEk@g@k@k@CCMMDO@EDMBMBOBQBO@KBM?G@OBQ?G@MBQ@MBMBMBOBOBMFSDSBGBIBGHOvAkE@EHQGEECa@_@ECMKKIwAiA_CmBq@m@ECIIOKoAcAs@i@KIIIOMgA{@QMCCGGGE_@[m@g@a@[kA_ACCECKGKGWSQOwAkAGEGEu@o@CCMIMKGEYSeAq@OKa@WGG[Sy@g@w@k@s@e@GEGE??YQgAu@c@[QKc@YMKKG@EBK@EVo@@EDKDM@Cb@cAFOBIt@oBBEDUJFBBFDx@l@??"
            },
            {
                "from": "order-1001",
                "to": "order-1002",
                "reachable": true,
                "distance_meters": 3108,
                "duration_seconds": 390,
                "geometry": "elwtGl}|_Mx@n@BBFD\\ZDDDBz@l@`@\\~BdB~AjAf@\\DDBBLDEPEJe@zAADENGNCFW|@Y|@CFA@ELCHGRq@jBABu@tBCHAFEJGNADg@vAKXq@lBABEHAHgA|C_@fASf@ADGPO^JHbAt@`CrBBBJHLJhCzBJL~BvBFDJJHF~@r@zAdABBHFLHdDfCBBFFFDJHvDlCRJDBRHXPx@f@D@HHJFVV|@x@BBLJTRJJTTlBdBLL`@\\h@f@ZXNLr@p@BBB@JJJHv@r@j@h@DDNLJJp@l@HHj@j@DBLLRRfB`BBBJJHFv@r@x@t@B@HHJJz@v@RRl@j@BBHHJHhAfAj@j@BBNLHHLLVT|@z@HFIPw@tBmAbDy@vBe@pACDIPIRg@pAO\\{A`ECDAFEJHHp@p@??"
            }
        ],
        "totals": {
            "distance_meters": 4948,
            "duration_seconds": 635,
            "legs": 2,
            "unreachable_legs": 0
        }
    },
    "meta": {
        "region": "NA",
        "profile": "car",
        "geometry": true,
        "geometry_format": "polyline",
        "mode": "sync"
    }
}

What it costs

One call, whatever its size.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return