• Home
  • Guides
  • Reference
  • Support

    Show / Hide Table of Contents
    • API Overview
      • Overview
      • Authentication
      • Retrieving API Results
      • Referenced vs Inline Entities
      • Choosing API Response Data
      • Handling API Errors
    • separator
    • Vehicle Routing Endpoints
      • Path
    • Optimization Endpoints
      • Instantiate
      • Build
      • Assignment Restrictions
      • Optimize
      • Sequence
      • Evaluate
      • Recommend
      • Insert
      • Centroids
      • Zones
      • Consolidate By Job Restrictions
      • Consolidate By Route Assignments
    • Geocoding Endpoints
      • Geocode
      • Reverse Geocode
    • Task Endpoints
      • List
      • Status
      • Result
      • Cancel
    • Sandbox Endpoints
      • List
      • Create
      • Rename
      • Retrieve
      • Update
      • Delete
      • Revisions
      • Add Revision
      • Expiry
      • Permissions
    • Verizon Connect Fleet Integration Endpoints
      • Pull Platform Data
      • Sync Platform Data
      • List Platform Territories
    • Other Endpoints
      • Canonicalize
      • Route Cards
      • Validate
      • Version
    • separator
    • Request Types
      • problem
      • capacity_metric
      • depot
      • driver
      • driver_break
      • job
      • job_template
      • job_type
      • load_amount
      • marker
      • problem_defaults
      • route
      • schedule
      • settings
      • shift
      • shift_override
      • shift_pattern
      • shift_pattern_assignment
      • stop
      • vehicle
      • zone
      • variance
    • Response Types
      • instantiate_response
      • problem_response
      • problem_aggregates
      • driver_response
      • geocoded_location
      • recommend_option
      • route_response
      • schedule_response
      • schedule_instantiate_response
      • stop_response
      • violation
    • Meta Types
      • task_redirect_response
      • task_status_response
      • validate_response
    • Sandbox Types
      • delta
      • array_delta
      • dict_delta
      • keyed_array_delta
      • object_delta
      • set_delta
      • revision
      • revision_created_response
      • revision_response
      • sandbox_response
    • Common Types
      • date_range
      • day_of_week
      • hazmat_load_type
      • id
      • latlon
      • stop_type
      • time_window
      • custom
      • polygon
    • Primitive Types
      • boolean
      • date
      • datetime
      • float
      • integer
      • string
      • timespan

    Vehicle Routing

    • POST https://routecloud.telogis.com/v1/path.
    • Authentication required.
    • Request body: path_request.
    • Response body: path_response.

    Status Codes

    • 200 - Success.
    • 400 - The input is invalid. The response is an error_response.
    • 401 - Authentication required.

    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"
                    }
                ]
            }
        ]
    }