Vehicle Routing

Status Codes

Request

path_request

Name Type Description Default
path_encoding path_encoding_type Optional Sets the format in which path geometry will be returned see Path Geometry 'json'
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.
intersection latlon Optional. The map coordinates of where the address intersects with the street.
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.

Path Geometry

When return_path is true the response will include a list of latitude, longitude points suitable for drawing the path on a map.

By default this will be returned as a JSON array of latlon[]:

// Default JSON Encoding of "Path"
{
	"path_to_stop": [
		"-43.500337,172.431008",
		"-43.501135,172.430719",
		"-43.501774,172.434062",
		"-43.500658,172.434467"
	]
}

While simple to work with, this can result in large response sizes, with a negative effect on client latency and bandwidth requirements. For production scenarios we recommend the use of the path_encoding 'encoded_polyline' option. When enabled the path geometry will be returned encoded as a string in the path_to_stop_enc property:

// encoded_polyline option
{
	"path_to_stop_enc": "bdohGy|l{_@|Cx@~B{S}EqA",
}

The encoding scheme used has been published by Google and is widely supported in geospatial platforms. Google's implementation in javascript can be found here https://github.com/googlemaps/js-polyline-codec

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 with path_request.path_encoding 'json'.
path_to_stop_enc latlon[] The path to the stop from the previous stop. Included when routing_options.return_path is set to true with path_request.path_encoding 'encoded_polyline'.
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"
                },
                {
                    "type": "off_street",
                    "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"
                }
            ]
        }
    ]
}

Get path of travel for visualization.

Request

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

{
  "path_encoding": "encoded_polyline",
  "routes":[
    {
      "routing_options":{
        "return_path": true
      },
      "vehicle": {
        "vehicle_type": "truck"
      },
      "stops":[
        {
          "type": "vehicle",
          "location": "-43.520772,172.648119",
          "heading": 90
        },
        {
          "type": "off_street",
          "location": "-43.526016,172.652142"
        }
      ]
    }
  ]
}

Response

{
    "routes": [
        {
            "distance_meters": 948.0,
            "driving_time": "00:02:54",
            "stops": [
                {
                    "arrival_datetime": "2023-02-23T02:40:41+00:00",
                    "time_to": "00:00:00",
                    "distance_to_meters": 0.0,
                    "location": "-43.520772,172.648119"
                },
                {
                    "arrival_datetime": "2023-02-23T02:43:35+00:00",
                    "time_to": "00:02:54",
                    "distance_to_meters": 948.0,
                    "location": "-43.526016,172.652142",
                    "path_to_stop_enc": "zcshGwiw|_@?mC?iA?yA?kAAoALYvAIdH@r@?d@?\\?XCTITIVQZSVS\\WZQ\\Kb@GVAX@^D\\L`@Tn@^j@Zp@RJm@Bw@@y@Aq@MsAYF"
                }
            ]
        }
    ]
}