Time Window Routing

The POST Time Window Routing operation allows user to optimize the stops sequence.

Request URL

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

Request Element

The operation takes a JSON format data in the POST body.

Settings

Route

Route Options

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

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      // trunk only
   },
   "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":0,
         "CustomRoadSpeeds":[
            {
               "RoadCategory":1,
               "Speed":0
            }
         ]
      },
      "Stops":[
         {
            "Location":{
               "Address":{
                  "StreetAddress":"",
                  "City":"",
                  "State":"",
                  "Zip":"",
                  "County":"",
                  "Country":"",
                  "SPLC":"",
                  "CountryPostalFilter":0,
                  "AbbreviationFormat":0
               },
               "Coords":{
                  "Lat":"0.000000",
                  "Lon":"0.000000"
               },
               "Region":4,
               "Label":"",
               "PlaceName":""
            },
            "TimeWindow":{
               "StartTime":"00:00",
               "EndTime":"11:59"
            },
            "SecondTimeWindow":{
               "StartTime":"00:00",
               "EndTime":"11:59"
            },
            "BlockTimeWindow":{
               "StartTime":"00:00",
               "EndTime":"11:59"
            },
            "WaitTime":0,
            "IsBreak":false,
            "IsStatic":false,
            "UniqueClusterID":""            // trunk only
         }
      ]
   }
}
                

Sample Response

 {
   "TotalETA":"00:00",
   "TotalDistance":"0.00",
   "Stops":[
      {
         "Location":{
            "Address":null,
            "Coords":{
               "Lat":"0.000000",
               "Lon":"0.000000"
            },
            "Region":4,
            "Label":"",
            "PlaceName":""
         },
         "OriginalPosition":0,
         "ETA":"00:00",
         "Distance":"0.00",
         "TimeWindowMet":false,
         "SlackTime":0
      }
   ],
   "RemovedStops":[
      {
         "Location":{
            "Address":{
               "StreetAddress":"",
               "City":"",
               "State":"",
               "Zip":"",
               "County":"",
               "Country":"",
               "SPLC":"",
               "CountryPostalFilter":0,
               "AbbreviationFormat":0,
               "CountryAbbreviation": "US"
            },
            "Coords":{
               "Lat":"0.000000",
               "Lon":"0.000000"
            },
            "Region":4,
            "Label":"",
            "PlaceName":""
         },
         "OriginalPosition":0,
         "Error":""
      }
   ]
}
                

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. Fuel optimization requested, but time window routing cannot use FuelOptions. This property will be ignored.
   • Occurs when FuelRoute is provided and set to true in RouteOptions.


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


7. 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.


8. 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.


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


10. 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.


11. 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.


12. 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.


13. 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.


14. 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.


15. 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.


16. 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.


17. 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.


18. 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.

Errors

1. Unlicensed for time window routing
   • Request is sent but the user isn't licensed to use time window routing.


2. Request body sequence must be supplied and contain a route with more than 3 stops.
   • Request sent with no TimeWindowSequence provided.
   • Request sent with no Route provided.
   • Request sent with no Stops provided.
   • Request sent with fewer stops in Stops list than minimum number of stops allowed.


3. Maximum number of stops allowed for time window routing is 200.
   • Request sent with more stops in Stops list than maximum number of stops allowed.


4. Stop #[index]: is null.
   • Can only occur if a Stop is provided with no information.


5. Stop #[index]: unable to read time window StartTime
   • Inavlid StartTime in last stop in Stops list.


6. Stop #[index]: unable to read time window EndTime.
   • Invalid EndTime in last stop in Stops list.


7. Stop #[index]: TimeWindow must be supplied.
   • Stop missing TimeWindow property.


8. Stop #[index]: TimeWindow StartTime and EndTime must be supplied
   • Stop has TimeWindow without supplying StartTime and EndTime.


9. Stop #[index]: TimeWindow StartTime does not match the sequence's time format [time format].
   • Time window supplied StartTime that is not in the correct format for Settings property's TimeFormat.


10. Stop #[index]: TimeWindow EndTime does not match the sequence's time format [time format].
    • Time window supplied EndTime that is not in the correct format for Settings property's TimeFormat.


11. Stop #[index]: is a depot and cannot be a break stop.
    • Either the first or last stop in Stops list has IsBreak set to true.


12. Stop #[index]: has block time window defined but is a break stop.
    • Stop has BlockTimeWindow defined and IsBreak set to true.


13. Stop #[index]: has second time window defined but is a break stop.
    • Stop has SecondTimeWindow defined and IsBreak set to true.


14. Stop #[index]: is a depot and is static by default. It has to be static but it is not required to mark it as static.
    • Either the first or last stop in Stops list has IsStatic set to false.


15. Stop #[index]: is a depot and cannot have a blocked time window.
    • Either the first or last stop in Stops list has BlockTimeWindow provided.


16. Stop #[index]: BlockTimeWindow StartTime and EndTime must be supplied.
    • Stop has BlockTimeWindow without supplying StartTime and EndTime.


17. Stop #[index]: BlockTimeWindow StartTime does not match the sequence's time format [time format].
    • Blocked time window supplied StartTime that is not in the correct format for Settings property's TimeFormat.


18. Stop #[index]: BlockTimeWindow EndTime does not match the sequence's time format [time format].
    • Blocked time window supplied EndTime that is not in the correct format for Settings property's TimeFormat.


19. Stop #[index]: is a depot and cannot have a second time window.
    • Either the first or last stop in Stops list has SecondTimeWindow provided.


20. Stop #[index]: SecondTimeWindow StartTime and EndTime must be supplied
    • Stop has SecondTimeWindow without supplying StartTime and EndTime


21. Stop #[index]: SecondTimeWindow StartTime does not match the sequence's time format [time format].
    • Second time window supplied StartTime that is not in the correct format for Settings property's TimeFormat.


22. Stop #[index]: SecondTimeWindow EndTime does not match the sequence's time format [time format].
    • Second time window supplied EndTime that is not in the correct format for Settings property's TimeFormat.


23. Stop #[index]: you can either provide SecondTimeWindow or BlockTimeWindow but not both.
    • Stop has both BlockTimeWindow and SecondTimeWindow provided.


24. Stop #[index]: cannot be static and a break stop at the same time.
    • Stop has both IsBreak and IsStatic set to true.


25. Stop #[index]: WaitTime must be supplied.
    • Stop does not have WaitTime property.


26. Stop #[index]: has invalid WaitTime.
    • Stop has WaitTime less than 0 or a value greater than the highest possible integer value (currently 2,147,483,647).


27. Stop #[index]: must provide Location property for a time window stop.
    • Stop does not have Location property.

Optmization

These errors also cause the response to fail, like validation, only they occur during the actual optimization logic.

Null optimizer results.
1. • Occurs if the results returned from core code are empty.
   • Sanity check that can only happen if the build properties are not set properly during compilation or something goes horribly wrong with CLI unmanaged to managed code conversions.


2. Unable to get stop results.
   • Occurs if the stop list returned from core code is empty.
   • Sanity check that can only happen if something goes horribly wrong with CLI unmanaged to managed code conversions.


3. Optimization API uninitialized.
   • Sanity check that can only happen if the core code API cannot initialize due to incorrect build properties, lack of memory or other indeterminate internal errors.


4. Unable to make an optimizer to run process.
   • Sanity check that can only happen if the core code API cannot initialize due to a lack of memory or other indeterminate internal errors.


5. Stop options did not match stops.
   • Sanity check that can only happen if there was an error in the CLI managed to unmanaged conversions.


6. Date or OverrideRestrict route options invalid.
   • Sanity check that can only happen if Date somehow gets set to a value other than PCMiler's default (0) by being exposed to time window routing or if validation fails to properly set OverrideRestrict


7. Depot(s) non-geocodable.
   • Either the first or last stop in Stops list or both were not able to be geocoded, even with a valid Location property.


8. Depot(s) too far away from other stops.
   • Either the first or last stop in Stops list or both are farther away from all other stops than the distance defined by MaxAirTravelDistanceFromDepot.


9. An unknown error occurred.
   • Sanity check that can only happen if an internal error occurred that did not throw an exception or cause a crash.

Stops

1. Geocode
   • Stop was not able to be geocoded, even with a valid Location property.


2. Over Max Distance from Other Stops
   • Stop is too far away from all other stops


3. Invalid Stop Time Window
   • Stop has TimeWindow StartTime greater than EndTime.
   • Stop has TimeWindow EndTime less than the first stop in Stops list's TimeWindow StartTime if RemoveStopIfTimeWindowBeforeStartTime is set to true.


4. Invalid Stop Wait Time
   • Stop has WaitTime less than 0 or a value greater than the value defined by MaxWaitTime.


5. Invalid Break Stop Wait Time
   • Stop has WaitTime less than 0 or a value greater than the value defined by MaxBreakWaitTime and has IsBreak set to true.
6. Invalid Static Stop Placement
   • Stop has IsStatic set to true but is not placed at the beginning or end of the sequence.
7. Unable to insert break stop into sequence
   • Stop has IsBreak set to true but was not able to be inserted into the final optimized sequence.
   • This is not actually an error, as it can only happen because the final stop in Stops list was reached before the the break stop's StartTime.


8. Unknown
   • Sanity check that can only happen if a stop was mistakenly added to the RemovedStops list without actually having an error.