Vehicle Routing

Status Codes

Request

path_request

Name Type Description
routes path_request_route[] Each route, specifies a list of locations to route between.

path_request_route

Name Type Description Default
id string Optional Can be used to correlate routes in the request/response
routing_options routing_options Options to customize routing behavior.
vehicle vehicle The vehicle for this route. Vehicle with vehicle_type 'auto'
stops path_request_stop Locations to visit

path_request_routing_options

Name Type Description Default
route_with_traffic boolean If 'true', route selection and arrival times will account for predicted traffic conditions. false
routing_date_time datetime The date and time the route starts. The current time
return_path boolean If 'true', the response will include a list of latlon, suitable for displaying the route on a map false

path_request_stop

Name Type Description
type path_request_location_type Optional Defines the type of location to support more accurate routing.
location latlon The location of the stop.
heading float Only applies for type 'vehicle'. Current direction of travel specified in degrees clockwise from North. Valid range [0, 360)

path_request_location_type

Locations provided in the request will not always precisely match the location of a road in our system, for example due to limited GPS accuracy, so the location must be mapped to a road for routing.

Location types can be used to obtain a more accurate mapping of locations to our road network data.

'on_street' and 'off_street' are used to define locations were a vehicle will stop. Routing will avoid mapping to a road where it is unsafe to stop, or a road that cannot be accessed from off street, such as raised highways.

The 'vehicle' type is used to specify the current location of a vehicle when enroute, and allows the inclusion of a heading to provide the current direction of travel.

If no type is specified, locations will be mapped to the closest road without any restrictions.

Value Description
off_street A stop away from the road, for example in a parking lot, the route will include travel time to the nearest accessible road.
on_street A stop on the side of a road, the location will be adjusted to the nearest accessible road.
vehicle Used to specify the current location of a vehicle when enroute, the location will be adjusted to the nearest road, a heading can also be included to provide the current direction of travel.

Response

path_response

Name Type Description
routes path_response_route[] Driving information for each requested route. Returned in the same order as path_request.routes

path_response_route

Name Type Description
id string Will match the corresponding path_request_route.id in the request.
distance_meters float The projected total distance of the route in meters.
driving_time timespan The projected total time spent driving the route.
stops path_response_stop[] Driving information from the previous location to each stop. Returned in the same order as path_request_route.stops
error error_response Returned if a route was unable to be calculated.

path_response_stop

Name Type Description
location latlon The location of the stop.
arrival_datetime datetime The date and time the driver is projected to arrive at the stop.
time_to timespan The amount of time spent driving to the stop from the previous stop.
distance_to_meters float The distance driven to reach the stop from the previous stop, in meters.
path_to_stop latlon[] The path to the stop from the previous stop. Included when routing_options.return_path is set to true.
violations violation[] If violations are returned there is no safe route for this leg. The given route should be reviewed before use.

Examples

Estimated time of arrival while enroute.

Request

POST https://routecloud.telogis.com/v1/path

{
    "routes":[
        {
            "routing_options": {
                "route_with_traffic": "true"
            },
            "vehicle": {
                "vehicle_type": "truck"
            },
            "stops":[
                {
                    "type": "vehicle",
                    "location": "51.793737, -3.175964",
                    "heading": "90"
                },
                {
                    "Location": "51.851706,-2.64961"
                }
            ]
        }
   ]
}

Response

{
    "routes": [
        {
            "stops": [
                {
                    "arrival_datetime": "2022-08-18T11:31:00Z",
                    "time_to": "00:00:00",
                    "distance_to_meters": 0.0,
                    "location": "51.793737,-3.175964"
                },
                {
                    "arrival_datetime": "2022-08-18T12:08:04Z",
                    "time_to": "00:37:04",
                    "distance_to_meters": 46232.0,
                    "location": "51.851706,-2.649610"
                }
            ]
        }
    ]
}