RESTful APIs

Time Window Routing

Contents

This API performs “Time Window Routing Optimization” on a sequence of stops. Time window optimization groups stops in a logical and efficient order while also taking into account specific time windows for arriving at each stop. WaitTime—the time the driver will spend at the stop—can also be taken into account to further enhance ETA accuracy.

POST /route/optimize?region={region}&dataset={dataset}

Resource URL

https://pcmiler.alk.com/apis/rest/v1.0/service.svc/route/optimize?region={region}&dataset={dataset}


Element Definition Required
The POST Body Object contains Settings and Route System Object. Y
region The data region in which the stops in the sequence are located. Valid values are NA, EU, OC and SA. N
dataset The regional dataset. Possible values: Current (Default), PCM_EU, PCM_OC, PCM_SA, PCM_AF, PCM_AS, PCM_ME, PCM_GT, PCM_WW and PCM_NA. N

POST Body

Settings

Element Description Data Type Value/Example
Method Specifies if the process is to optimize the sequence or calculate the estimated time of arrival on an already optimized sequence.
Optional and defaults to optimization of the sequence. 
Enum
1 - Optimize
2 - ETA
TimeFormat The format of the time in time windows specified per stop.
Optional and defaults to the 24-hour format. 
Enum
1 - Hour24 (00:00 - 23:59)
2 - Minutes (after midnight)
3 - Hour12 (12:00am - 11:59pm)
MaxClusterCount The maximum number of clusters of stops allowed to be generated. Optional and defaults to 40 clusters. 
integer
MinClusterCount The minimum number of clusters of stops allowed to be generated.
Optional and defaults to 30 clusters. 
integer
MaxAirTravelTimeForCluster The maximum air travel time in seconds that any two stops can be apart from each other and still be allowed to be clustered together. It also determines the maximum air travel time in seconds that is allowed for traveling between all stops in a cluster.
Optional and defaults to 180 seconds. 
integer
MinAirTravelTimeForCluster The minimum air travel time in seconds that is allowed for traveling between all stops in a cluster. Optional and defaults to 6 seconds. 
integer
MaxAirTravelDistanceForCluster The maximum air travel distance that is allowed for traveling between all stops in a cluster. Optional and defaults to 100 miles. 
double
MaxAirTravelDistanceFromDepot The maximum air travel distance that is allowed for traveling between any stop and the start and end depots. Optional and defaults to 200 miles. 
double
MaxGridsForMatrixCalculation The maximum number of grid expansions allowed when building a time/distance matrix for sequences and clusters.
Optional and defaults to 60. 
integer
GeocodingDistanceThreshold How far off a stop is allowed to be from the original or Geocoded latitude and longitude once snapped to a grid link.
Optional and defaults to 0.497097 miles (800 meters).
Use kilometers by setting DistanceUnits under Route Options. 
double
GeocodingConfidenceThreshold The confidence level of a Geocode search for stops.
Optional and defaults to 2 (good confidence). 
integer
1 - Exact
2 - Good
3 - Uncertain
4 - Fail
MaxWaitTime The maximum time in seconds a driver is allowed to wait at a stop. Optional and defaults to 1800 seconds. 
integer
MaxBreakWaitTime The maximum time in seconds a driver is allowed to wait at a break stop. Optional and defaults to 7200 seconds. 
integer
MaxServiceTimeToClusterStops The maximum total wait time in seconds allowed for stops in a cluster.
Optional and defaults to 2400 seconds. 
integer
MaxServiceTimeToClusterLevel0Stops The maximum amount of combined service time. The stops at service level 0 (pre-10AM stops) inside a cluster are allowed to have. Optional and defaults to 600 seconds. 
integer
MaxServiceTimeToClusterLevel1Stops The maximum amount of combined service time. The stops at service level 1 (pre-noon stops) inside a cluster are allowed to have. Optional and defaults to 600 seconds. 
integer
MaxTravelTimeToBreakCluster The maximum total travel time in seconds a cluster can reach before being forced to break smaller clusters. Optional and defaults to 300 seconds. 
integer
AvgTravelTimeToBreakCluster The travel time in seconds that is used for breaking a cluster into smaller clusters if the travel time between any two stops in that cluster exceeds it. Optional and defaults to 180 seconds. 
integer
AvgTravelTimeRatioToBreakCluster The ratio of stops over the average time to break a cluster to the stops under the average time. Optional and defaults to 3. 
integer
MaxTimeBeforeLateInBlockTime The max time in seconds into a stop’s blocked time window the driver arrives at the stop before it is considered late. Optional and defaults to 900 seconds. 
integer
UTurnCost The cost of making a U-turn regardless of vehicle type. This value doesn’t actually match any particular cost or unit of measurement used elsewhere. In theory, 1,000 is roughly 1 mile.
Optional and defaults to a value assigned by vehicle type. 
integer
PrioritizePremiumStops Pick a sequence with fewer stops with pre-noon and pre-six PM time windows that are late instead of favoring shorter ETAs or total distance. Optional and defaults to true. 
boolean
GeocodingUseLocationPlusAddress Geocode stops using latitude, longitude, and an address (if an address is provided) instead of finding the nearest grid link. Optional and defaults to false. 
boolean
AllowGeocodeMultiMatch Whether or not it’s okay that a Geocode search returns more than one match for a stop. Optional and defaults to true. 
boolean
RemoveStopIfTimeWindowBeforeStartTime Whether or not a stop should be removed if its time window occurs before the start depot’s start time. Optional and defaults to true. 
boolean
UniqueClusterStrictness Sets how unique cluster IDs affect clustering logic. Optional and defaults to 0. 
Enum
0 - Unique cluster IDs will be ignored. (Default)
1 - Unique Cluster IDs are taken into consideration
2 - Normal clustering and re-clustering logic is not used. Stops will be clustered together using unique cluster IDs only.
HistoricSpeedFixedDayOfWeek Live traffic is not used in Time Window routing. This parameter sets which day of the week historical speed data, based on your start time, will be used for routing. Optional and defaults to -1 (Current day). 
Enum
-1 - Current day
0 - Sunday
1 - Monday
2 - Tuesday
3 - Wednesday
4 - Thursday
5 - Friday
6 - Saturday
UseSideOfStreet Sets whether or not stops should be clustered and sequenced in such a way that the driver will make deliveries on the same side of the street as the direction of travel. Optional and defaults to false. 
Boolean
UseTraffic (Requires a license for access to traffic data) Set to false and historical speed data will not be used when calculating the optimized sequence of stops. When this value is set, and the user is not licensed for traffic, an error will be returned. Optional and defaults to true. 
Boolean
FinalStopIsEndDepot When set to true, the final stop in the time window stop list is a fixed end depot. If set to false, the final stop will be considered another delivery stop and will not be in a fixed position. Optional and defaults to true. 
Boolean
RoutePathOptions Instead of making a separate call to the Route Path API, you can use this object to request a route path response along with the time window optimization response. This can be beneficial versus directly calling the Route Path API, which does not take into consideration wait times, break times, etc. Optional. 
Object
See RoutePathOptions Object for values.
ApplyStopLocalTimeZones When set to false, it forces all time windows to behave as if they were in the same time zone. By default, the Time Window Routing API automatically adjusts time windows, ETAs and ETDs to account for a stop’s local time zone. Optional and defaults to true. 
Boolean

RoutePathOptions

Element Description Data Type Value/Example
Generate When set to true, a route path response will be included with the time window optimization response. When set to false, the route path response will be null. Optional and defaults to false. 
Boolean
ReduceResponsePoints Set to true to minimize the points in between stops for routing and routing directions. This behaves the same way as it does in the Route Path API. Optional and defaults to false. 
Boolean
StopsAsViaPoints Set to true to treat stops between the depots as waypoints. This behaves the same way as it does in in the Route Path API. However, in the original API, it can set all stops as waypoints. The start and end depots of a time window optimization cannot be waypoints. Optional and defaults to false. 
Boolean

Route

Element Description Data Type Value/Example
Name Name of the trip 
string
Options Route Options Object.
Stops A list of stops that include time window restrictions in which they must be reached.
It consists of Location Object and TimeWindow Object.
The minimum required number of stops is 4.
The maximum number of stops is 500.

Route Options

Element Description Data Type Value/Example
VehicleType The type of the vehicle driving the route.
Optional and defaults to default vehicle type 0. 
Enum
0 - Truck
1 - LightTruck
2 - Auto
RoutingType The type of route you want to calculate.
Optional and defaults to 0. 
Enum
0 - Practical
1 - Shortest
2 - Fastest
HighwayOnly Indicates whether to use highways.
This parameter is always set to false because Time Window Routing requires the use of local streets. 
boolean
FuelRoute Whether or not a fuel optimized route is desired.
Optional and defaults to false.
This parameter is ignored by time window optimization. If “true” is passed, it is set to “false” and a warning is returned in the response header. 
boolean
UseAvoidsAndFavors Whether or not to use avoids and favors. Optional and defaults to false.
This parameter is a remnant of legacy code and is no longer necessary. Use AFSetIDs or AFSetNames to select the Route Modifier (avoids/favor) sets you’d like to apply to this route. 
boolean
UseCrossStreetTurnAvoidance When set to true, it reduces the chances the route generated includes turns that go across the street in front of oncoming traffic. These turns will still be included if there is no reasonable alternative.
Optional and defaults to false. (For auto and van Vehicle Routing Profiles only) 
boolean
ClassOverrides Represents a route class override to a special network.
Optional and defaults to 0. 
boolean
0 - None
1 - FiftyThreeFoot
2 - NationalNetwork
3 - FiftyThreeFoot, NationalNetwork
DistanceUnits Represents whether to return distances in miles or kilometers.
Optional and defaults to 0. 
boolean
0 - Miles
1 - Kilometers
TollDiscourage Whether or not tolls should be discouraged on the route.
Optional and defaults to false. 
boolean
BordersOpen Set to True to allow international border crossings, False to avoid or reduce number of international border crossings. For example, if all your stops are in the “lower 48” United States, the resulting route will stay in the United States even if the most practical or shortest route would normally involve some Canadian mileage. For EU travel, setting this to False will reduce the number of EU border crossings where possible and the route will follow the best path within the country from which the route originates.
Optional and defaults to True. 
boolean
OverrideRestrict Whether or not to override truck restrictions.
Optional and defaults to false.
If this property is set to “true”, then it is set to false and a warning is returned in the response header. This affects link costs in PC*Miler and allows differences between it and CoPilot. 
boolean
HazMatType Indicates the hazardous material type. See details in Glossary.
Optionals and defaults to 0. 
Enum
0 - None
1 - General
2 - Caustic
3 - Explosives
4 - Flammable
5 - Inhalants
6 - Radioactive
RouteOptimization The method by which to optimize the route stops.
Optional and defaults to 0.
If any value other than “None” is provided, then it is set to 0 and a warning is returned in the response header. Time window optimization requires the start and end depot to be fixed so this value is at ends with the process. 
boolean
0 - None
1 - Thruall
2 - DestinationFixed
TruckCfg TruckConfig object. Configures truck size and statistics.
Optional.
Units Specifies whether English or metric units describe vehicle dimensions.
Optional and defaults to 0. 
Enum
0 - English
1 - Metric
Height Represents the height of the truck in feet and inches, or meters depending upon the units.
Maximum value is 13'6" or 4.1148 meters.
Optional and defaults to “13'6"” in all regions except Europe, which is “12'6"”. 
string
Length Represents the length of the truck in feet or meters, depending upon the units.
Maximum value is 53’ or 16.1544 meters.
Optional and defaults to “48’” in all regions except Europe, which is “54'1"”. 
string
Width Represents the width of the truck in inches or meters, depending upon units.
This value can be 96" and below, 102" and above or 98".
Optional and defaults to “96"” for all regions. 
string
Weight Represents the weight of the truck in pounds or kilos, depending upon units.
Acceptable values can be up to 132,000 pounds or 59,874 kilos.
Optional and defaults to “80000”. 
string
Axles The number of axles on the truck.
Acceptable values are 2 through 14.
Optional and defaults to 5. 
integer
LCV Indicates whether the truck is a multi-trailer or longer combination vehicle.
This is used for calculation of toll costs, and only for North American region.
Optional and defaults to false. 
boolean
HubRouting Whether or not to enable hub routing.
Optional and defaults to false. 
boolean
AFSetIDs The IDs of the Route Modifier (avoid/favor) sets that should be applied to the route. The format is comma separated IDs. The IDs are integers. Set to [-1] to select all sets. List of integers
afSetNames A list of comma-separated names of the Route Modifier (avoid/favor) sets that should be applied to the route. Default is an empty set. List of strings
ElevLimit Represents elevation limit when generating a route.
Elevation units can be either meters or feet determined by “DistanceUnits”. Miles=feet, Kilometers=meters
Limit will be ignored if: 1.Routing is deemed impractical with the limit. 2.A stop is located at an elevation higher than the limit.
Optional and defaults to 0. 		Unsigned Integer
FerryDiscourage Whether or not to avoid ferries while routing.
Optional and defaults to 0. 
boolean
HoSOptions This is an object used to define a driver’s service times and rule sets.
Optional and defaults to null.
This object is at ends with the entire time window optimization process and should not be defined. However, an warning will only be thrown if “Enabled” is set to “true” and then the object will be set to null. 		HoSScheduleType object
Enabled Whether or not to use the defined “HoSScheduleType” object.
Optional and defaults to false.
If this is “true”, an warning will be returned and the parent “HoSScheduleType” object will be set to null. 
boolean
SideOfStreetAdherence How strict to be in order to avoid the destination being on the opposite side of the street.
Optional and defaults to 0. 
Enum
0 - Off
1 - Minimal
2 - Moderate
3 - Average
4 - Strict
5 - Adhere
6 - StronglyAdhere
GovernorSpeedLimit Maximum average road speed to use in route calculations that overrides all other road speeds when they are above this value.
Valid value is between 1 and 100 mph.
This setting is optional and turned off by default (no governor speed). 
integer
RestrictionZones (Europe Only) An object that sets whether the route can pass through a CongestionZone, a LowEmissionZone, or an UltraLowEmissionZone. For each type of zone, three settings are available:
Allow the route to pass through the zone (Default).
Avoid the zone and route around it.
Warn that the route enters the zone. 
object
“RestrictionZones”: {
&nbsp"CongestionZone": Avoid,
&nbsp"LowEmissionZone": Allow,
&nbsp"UltraLowEmissionZone": Warn
}

Location

For a valid Location, one of the following must be defined. See details in Sample JSON Request.

  • Address object. It consists of StreetAddress, City, State, County, Country, SPLC and zip.
  • Coords object. It consists of Lat and Lon.

It is also valid to have both defined. As long as one of the above conditions are met, it doesn’t matter what else in “Location” is undefined or partially defined. If neither of the requirements are met, an error is returned for each invalid stop.

TimeWindow

Time windows can be set for any amount of time, but windows that are one hour or less may negatively impact results for routes with large numbers of stops.

Element Description Data Type
TimeWindow The window of time in which a stop must be reached.
It contains a string StartTime and string EndTime.
SecondTimeWindow It represents a second time window in which the stop can be reached.
It contains a string StartTime and string EndTime.
A single stop cannot have this and BlockTimeWindow defined at the same time.
BlockTimeWindow The window of time in which a stop cannot be reached within a time window.
It contains a string StartTime and string EndTime.
A single stop cannot have this and SecondTimeWindow defined at the same time.
StartTime The stop can only be reached on or after this time. The algorithm uses the StartTime entered for the first stop (origin) as the start time for the entire trip. The TotalETA, which is the estimated time of arrival to the last stop, through the entire sequence of stops, is based on that initial StartTime.
EndTime The stop can only be reached on or before this time.
WaitTime The period of time in which the driver will be at this stop in seconds. 
integer
IsBreak Whether or not this stop is actually where the driver takes a break. In this case, the time window represents how long the break is.
Optional and defaults to false.
A single stop cannot be a static stop and a break stop at the same time. 
boolean
IsStatic Whether or not this stop is not to change its position in the sequence when an optimized sequence is calculated. Static stops can only
appear at the beginning and the end of a sequence.
Optional and defaults to false.
A single stop cannot be a static stop and a break stop at the same time. 
boolean
UniqueClusterID This value coerces the routing algorithm to cluster together stops based on these IDs. It never uses only the unique cluster ID by itself and clusters can still break apart during sequencing. However, stops with the same unique cluster ID are more likely to be sequenced together in the end result. Optional and defaults to an empty string.
Set ClusterWithUniqueIDOnly to “true” in order to prioritize clustering by the unique cluster ID more than normal. 
string
DeliveryType This value coerces the routing algorithm to cluster together stops that have the same delivery type. The goal is to make deliveries first and complete pickups after all deliveries are made.
Values
0 - Unknown (Default)
1 - Delivery
2 - Pickup 
integer

Response parameters

The algorithm optimizes and re-orders the stops and the response returns that new order. The response also includes the following additional information about the trip.

Element Description Data Type
TotalETA The estimated time of arrival to the last stop, through the entire sequence of stops. It is calculated based on the StartTime entered for the first stop (origin) of the trip. 
string
TotalDistance The total distance traveled across all stops in the optimized sequence, rounded to two decimal places. 
string
OriginalPosition The position the stop was in within the request’s list of stops. 
integer
TimeWindowMet Whether or not the stop made its time window. 
boolean
SlackTime How early the driver will be to this stop in minutes. 
integer

Sample JSON Post Body 

{
    "Settings": {
        "Method": 1,
        "TimeFormat": 1,
        "MaxClusterCount": 40,
        "MinClusterCount": 30,
        "MaxAirTravelTimeForCluster": 180,
        "MinAirTravelTimeForCluster": 6,
        "MaxAirTravelDistanceForCluster": 100.0,
        "MaxAirTravelDistanceFromDepot": 200.0,
        "MaxGridsForMatrixCalculation": 60,
        "GeocodingDistanceThreshold": 0.497097,
        "GeocodingConfidenceThreshold": 2,
        "MaxWaitTime": 1800,
        "MaxBreakWaitTime": 7200,
        "MaxServiceTimeToClusterStops": 2400,
        "MaxServiceTimeToClusterLevel0Stops": 600,
        "MaxServiceTimeToClusterLevel1Stops": 600,
        "MaxTravelTimeToBreakCluster": 300,
        "AvgTravelTimeToBreakCluster": 180,
        "AvgTravelTimeRatioToBreakCluster": 3,
        "MaxTimeBeforeLateInBlockTime": 900,
        "UTurnCost": -2,
        "PrioritizePremiumStops": true,
        "GeocodingUseLocationPlusAddress": false,
        "AllowGeocodeMultiMatch": true,
        "RemoveStopIfTimeWindowBeforeStartTime": true,
        "UniqueClusterStrictness": 0,
        "HistoricSpeedFixedDayOfWeek": -1,
        "UseSideOfStreet": false,
        "UseTraffic": true,
        "RoutePathOptions": {
            "Generate": false,
            "ReduceResponsePoints": false,
            "StopsAsViaPoints": false
        }
    },
    "Route": {
        "Name": "",
        "Options": {
            "VehicleType": 0,
            "RoutingType": 0,
            "HighwayOnly": false,
            "FuelRoute": false,
            "UseAvoidsAndFavors": false,
            "ClassOverrides": 0,
            "DistanceUnits": 0,
            "TollDiscourage": false,
            "BordersOpen": true,
            "OverrideRestrict": false,
            "HazMatType": 0,
            "RouteOptimization": 0,
            "TruckCfg": {
                "Units": 0,
                "Height": "13'6\"",
                "Length": "48'",
                "Width": "96\"",
                "Weight": "80000",
                "Axles": 5,
                "LCV": false
            },
            "HubRouting": false,
            "AFSetIDs": [],
            "ElevLimit": 0,
            "FerryDiscourage": false,
            "HoSOptions": {
                "Enabled": false,
                "RemainingDriveTimeUntilBreak": 0.0,
                "RemainingDriveTime": 0.0,
                "RemainingOnDutyTime": 0.0,
                "HoSRuleType": 0,
                "RemainingCycleDutyTime": 0.0
            },
            "SideOfStreetAdherence": 0,
            "GovernorSpeedLimit": 50,
            "CustomRoadSpeeds": [
                {
                    "RoadCategory": 1,
                    "Speed": 55
                },
                {
                    "RoadCategory": 10,
                    "Speed": 65
                },
                {
                    "RoadCategory": 3,
                    "Speed": 31
                },
                {
                    "RoadCategory": 12,
                    "Speed": 45
                },
                {
                    "RoadCategory": 4,
                    "Speed": 25
                },
                {
                    "RoadCategory": 13,
                    "Speed": 30
                },
                {
                    "RoadCategory": 6,
                    "Speed": 16
                },
                {
                    "RoadCategory": 15,
                    "Speed": 25
                },
                {
                    "RoadCategory": 8,
                    "Speed": 12
                },
                {
                    "RoadCategory": 17,
                    "Speed": 18
                }
            ]
        },
        "Stops": [
            {
                "Location": {
                    "Address": {
                        "StreetAddress": "1 Independence Way",
                        "City": "Princeton",
                        "State": "NJ",
                        "Zip": "08540",
                        "County": "",
                        "Country": "",
                        "SPLC": "",
                        "CountryPostalFilter": 0,
                        "AbbreviationFormat": 0
                    },
                    "Coords": {
                        "Lat": "40.361007",
                        "Lon": "-74.599268"
                    },
                    "Region": "4",
                    "Label": "Origin Depot",
                    "PlaceName": ""
                },
                "TimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "WaitTime": 0,
                "IsBreak": false,
                "IsStatic": true,
                "UniqueClusterID": ""
            },
            {
                "Location": {
                    "Address": {
                        "StreetAddress": "4100 Quakerbridge Rd",
                        "City": "Lawrence TWP",
                        "State": "NJ",
                        "Zip": "08648",
                        "County": "",
                        "Country": "",
                        "SPLC": "",
                        "CountryPostalFilter": 0,
                        "AbbreviationFormat": 0
                    },
                    "Coords": {
                        "Lat": "40.280598",
                        "Lon": "-74.673943"
                    },
                    "Region": "4",
                    "Label": "First Delivery Stop",
                    "PlaceName": ""
                },
                "TimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "SecondTimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "WaitTime": 0,
                "IsBreak": false,
                "IsStatic": false,
                "UniqueClusterID": "",
                "DeliveryType": 1
            },
            {
                "Location": {
                    "Address": {
                        "StreetAddress": "457 North Harrison Street",
                        "City": "Princeton",
                        "State": "NJ",
                        "Zip": "08540",
                        "County": "",
                        "Country": "",
                        "SPLC": "",
                        "CountryPostalFilter": 0,
                        "AbbreviationFormat": 0
                    },
                    "Coords": {
                        "Lat": "40.306528",
                        "Lon": "-74.677430"
                    },
                    "Region": "4",
                    "Label": "Second Delivery Stop",
                    "PlaceName": ""
                },
                "TimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "BlockTimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "WaitTime": 0,
                "IsBreak": false,
                "IsStatic": false,
                "UniqueClusterID": "",
                "DeliveryType": 1
            },
            {
                "Location": {
                    "Address": {
                        "StreetAddress": "457 North Harrison Street",
                        "City": "Princeton",
                        "State": "NJ",
                        "Zip": "08540",
                        "County": "",
                        "Country": "",
                        "SPLC": "",
                        "CountryPostalFilter": 0,
                        "AbbreviationFormat": 0
                    },
                    "Coords": {
                        "Lat": "40.368513",
                        "Lon": "-74.654805"
                    },
                    "Region": "4",
                    "Label": "Destination Depot",
                    "PlaceName": ""
                },
                "TimeWindow": {
                    "StartTime": "00:00",
                    "EndTime": "11:59"
                },
                "WaitTime": 0,
                "IsBreak": false,
                "IsStatic": true,
                "UniqueClusterID": ""
            }
        ]
    }
}

Sample Response 

{
    "TotalETA": "00:48",
    "TotalDistance": "17.68",
    "Stops": [
        {
            "Location": {
                "Address": null,
                "Coords": {
                    "Lat": "40.361007",
                    "Lon": "-74.599268"
                },
                "Region": 4,
                "Label": "Origin Depot",
                "PlaceName": ""
            },
            "OriginalPosition": 0,
            "ETA": "00:00",
            "Distance": "0.00",
            "TimeWindowMet": true,
            "SlackTime": 0,
            "TimeWindow": {
                "StartTime": "00:00",
                "EndTime": "00:00"
            },
            "BlockTimeWindow": null,
            "WaitTime": 0,
            "UniqueClusterID": null,
            "DeliveryType": null
        },
        {
            "Location": {
                "Address": null,
                "Coords": {
                    "Lat": "40.306528",
                    "Lon": "-74.677430"
                },
                "Region": 4,
                "Label": "Second Delivery Stop",
                "PlaceName": ""
            },
            "OriginalPosition": 2,
            "ETA": "00:13",
            "Distance": "6.17",
            "TimeWindowMet": false,
            "SlackTime": 0,
            "TimeWindow": {
                "StartTime": "00:00",
                "EndTime": "11:59"
            },
            "BlockTimeWindow": {
                "StartTime": "00:00",
                "EndTime": "11:59"
            },
            "WaitTime": 0,
            "UniqueClusterID": null,
            "DeliveryType": 1
        },
        {
            "Location": {
                "Address": null,
                "Coords": {
                    "Lat": "40.280598",
                    "Lon": "-74.673943"
                },
                "Region": 4,
                "Label": "First Delivery Stop",
                "PlaceName": ""
            },
            "OriginalPosition": 1,
            "ETA": "00:25",
            "Distance": "3.51",
            "TimeWindowMet": true,
            "SlackTime": 0,
            "TimeWindow": {
                "StartTime": "00:00",
                "EndTime": "11:59"
            },
            "BlockTimeWindow": null,
            "WaitTime": 0,
            "UniqueClusterID": null,
            "DeliveryType": 1
        },
        {
            "Location": {
                "Address": null,
                "Coords": {
                    "Lat": "40.368513",
                    "Lon": "-74.654805"
                },
                "Region": 4,
                "Label": "Destination Depot",
                "PlaceName": ""
            },
            "OriginalPosition": 3,
            "ETA": "00:48",
            "Distance": "8.00",
            "TimeWindowMet": true,
            "SlackTime": 0,
            "TimeWindow": {
                "StartTime": "00:00",
                "EndTime": "11:59"
            },
            "BlockTimeWindow": null,
            "WaitTime": 0,
            "UniqueClusterID": null,
            "DeliveryType": null
        }
    ],
    "RemovedStops": [],
    "RoutePath": null
}

Errors and Warnings

Validation

Any errors or warnings that occur here happen when validating the incoming request JSON. Errors will cause a failure but warnings will allow the request to continue and be returned in the response header. Time window routing shares the same validations as other requests for requests, route options and stop locations. The following are unique to time window routing:

Warnings

  1. Settings property not provided. Using default values.
    Occurs when no Settings property provided.

  2. Method property not found in Settings. The value will be set to 1.
    Occurs when Settings is provided but Method is not.

  3. TimeFormat property not found in ‘Settings’. The value will be set to 1.
    Occurs when Settings is provided but TimeFormat is not.

  4. RouteOptions property not found in Route. Using default values.
    Occurs when Options is not provided in Route.

  5. Fastest routing type uses historical data. RoutingType will be changed to 0. Occurs when RoutingType is provided and set to 2 in RouteOptions.

  6. Time window routing cannot use RouteOptimization property. It requires its start and end depots to be fixed.
    Occurs when RouteOptimization is provided and set to any value other than 0 in RouteOptions.

  7. Time window routing cannot use HoSOptions property. Work time and schedule is implied by the optimized sequence’s results. Use break stops to mark breaks for the driver in the sequence.
    Occurs when HoSOptions is provided and “Enabled” is set to true in RouteOptions.

  8. Time window routing cannot use OverrideRestrict property. It impacts OverrideRestrictthe sequence.
    Occurs when OverrideRestrict is provided and set to true in RouteOptions.

  9. Stop #0: is a starting depot and does not need a valid EndTime value. Just provide the same value as StartTime.
    Occurs when the first stop in Stops list is provided an EndTime with a different value than its StartTime.

  10. Stop #[index]: is a ending depot and does not need a valid time window StartTime. Any value over 0 will be ignored.
    Occurs when the last stop in Stops list is given a StartTime with a value other than midnight.

  11. Stop #[index]: is a ending depot and does not need a valid time window EndTime. Any value over 0 will be ignored.
    Occurs when the last stop in Stops list is given a EndTime with a value other than midnight.

  12. Stop #[index]: is a depot and can never be a break stop. Explicitly marking IsBreak false is unnecessary.
    Occurs when either the first or last stop in Stops list has IsBreak set to false.

  13. Stop #[index]: is a depot and is static by default. Explicitly marking IsStatic true is unnecessary.
    Occurs when either the first or last stop in Stops list has “IsStatic” set to true.

  14. Stop #[index]: is a depot and does not need to wait. Any WaitTime above 0 will be ignored.
    Either the first or last stop in Stops list has WaitTime provided with a value greater than 0.

  15. Stop #[index]: SPLC provided but cannot be used by time window routing. This property will be ignored.
    Stop’s Location property has SPLC provided with a valid StreetAddress, City, State/Country and Zip.

  16. Stop #[index]: SPLC provided but time window routing requires StreetAddress, City, State/Country It cannot use this property.
    Stop’s Location property has SPLC provided with a valid StreetAddress, City, State/Country and Zip.

  17. Stop #[index]: Location property must have either valid address (complete with StreetAddress, City, State/Country) or valid latitude and longitude coordinates in order to be geocoded successfully.
    Stop’s Location property does not have valid Coords or StreetAddress, City, State/Country and Zip. This is only a warning because the stop will be removed with a geocode error.

Last updated June 7, 2024.
API Endpoint:
AWS Azure
Contents