Hours of Service Report

Contents

Available in North America only

The Hours of Service Report calculates estimated departure and arrival times for all stops using detailed hours of service (HOS) information. It will also report additional stops that were inserted to maintain hours of service compliance.

This report type is only accessible through the REST POST API.

Available for dataVersion 31 and Later

Hours of Service Report Request

POST Request

See details in POST Route Reports for how to setup and call the POST version of the Reports API. The table below details all of the hours of service options available as part of the HoSOptions object.

HoSOptions

Data Element	Description	Data Type	POST Only
`Enabled`	Are hours of service calculations and rest stop insertion enabled.	bool	False
`RemainingDriveTimeUntilBreak`	The available driving hours at origin before the driver needs to take a rest break. The format is in seconds.	double	False
`RemainingDriveTime`	The available driving hours at origin until the end of work day. The format is in seconds.	double	False
`RemainingOnDutyTime`	The available On-Duty hours available at origin until the end of work day. For Canada HOS this is the available On-Duty hours until the end of the work shift. The format is in seconds.	double	False
`CurrentOffDutyTime`	How much off-duty time the driver has already accumulated during the trip at the time the HOS report request is made. This value is used to offset the length of an upcoming rest break. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the `CurrentOffDutyTime` parameter. The format is in seconds.	double	True
`CurrentOffDutyTimeDriver2`	(For team driving only) How much off-duty time the driver has already accumulated during the trip at the time the HOS report request is made. This value is used to offset the length of an upcoming rest break. For example, if a driver is due for an end-of-day break, which is typically 10 hours, HOS logic will reduce that break duration by the amount of time entered in the `CurrentOffDutyTime` parameter. The format is in seconds.	double	True
`RemainingCanadaOnDutyTime`	For Canada HOS this is the available On-Duty hours at origin until the end of work day. The format is in seconds.	double	True
`RemainingTimeUntilFullDayBreak`	For Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed. The format is in seconds.	double	True
`HoSRuleType`	The hours of service rule currently in use. USFed607LH - 0, USFed708LH - 1, CanadaCycle1 - 2, CanadaCycle2 - 3, California808 - 4, Texas707 - 5, USShortHaul - 6, Europe -7.	`HoSScheduleType` ( Enum )	False
`RemainingCycleDutyTime`	The available Cycle duty time at origin until Cycle reset. The format is in seconds.	double	False
`CycleTimeGains`	An array of cycle time gains in seconds for the next 6 or 7 days.	double	True
`LastCycleResetDateTime`	The time of the last cycle reset for Canadian hours of service.	string	True
`Last24HourBreakDateTime`	The date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service.	string	True
`UseCycleReset`	Whether we do full cycle time reset or not.	bool	True
`TerminalDayStartTime`	The time of day used to determine when a 24-hour period defining a ‘day’ starts. The format should be “HH:mm:sszzz”	string	True
`UseCustomPlaces`	Whether to use custom places for HOS rest stops.	bool	True
`TeamDriving`	Whether there are team drivers.	bool	True
`CustomBreakDurations`	The custom break durations for hours of service rest stops.	`HoursOfServiceBreakDurations`	True
`AlternateHoSRuleType`	The alternate Hours of Service rule type to use if crossing international borders between the US and Canada. USFed607LH - 0, USFed708LH - 1, CanadaCycle1 - 2, CanadaCycle2 - 3, California808 - 4, Texas707 - 5, USShortHaul - 6.	`HoSScheduleType` ( Enum )	True
`POIStopsReturned`	Sets whether rest stops are returned as actual stop locations (POIs) along the route or only as the latitude/longitude coordinates for the last point along the route that a rest stop must be taken before a violation occurs. True = Use POIs (Default) False = Coordinates	bool	True
`HOSWindowStart`	Sets the time in minutes prior to when an HOS break is required that the algorithm should start looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and `HOSWindowStart` is set to 30, the window for inserting a rest stop begins at 1:30 p.m.	int	True
`HOSWindowEnd`	Sets the time in minutes prior to when an HOS break is required that the algorithm should finish looking for a rest stop to insert in the trip. The value can be between 10 and 60 minutes. For example, if a break is required at 2 p.m., and `HOSWindowEnd` is set to 10, the window for inserting a rest stop ends at 1:50 p.m. To maximize driving time, the algorithm will look for a stop as close as possible to the end of the window.	int	True

HoursOfServiceBreakDurations

Data Element	Description	Data Type
`ShortBreakDuration`	The short break duration. The format is in seconds.	double
`EndOfDutyBreakDuration`	The end of duty break duration. The format is in seconds.	double
`CycleResetBreakDuration`	The cycle reset break duration. The format is in seconds.	double
`DriverSwitchBreakDuration`	The driver switch break duration. The format is in seconds.	double
`BorderCrossingWaitDuration`	The border crossing wait duration. The format is in seconds.	double

Hours Of Service Report Response

Data Element	Description	Data Type	Value/Example
`type`	Describes the type of report and what it does.	string	HoursOfServiceReport
`DriverHoursOfServiceRemaining`	Drivers remaining hours of service at the end of the route.(Can be null)	Complex
`Stops`	The list of all the stops for the trip, including any newly inserted ones, with corresponding departure and arrival times and stop durations.	Complex
`TotalDrivingDuration`	Total drive time duration of the trip. Format is in decimal hours.	double
`TotalDuration`	Total duration of the trip including all stop times. Format is in decimal hours.	double
`SlackTime`	The time in hours for how early you are expected to arrive at the stop, based on its time window. It is only returned if your request specifies a time window for each stop using the `EarliestArrivalTime` and `LatestArrivalTime` parameters. It assumes a departure time of right now unless you specify a departure day and time using the `EstimatedTimeOptions` object.	double

HoursOfServiceRemaining

Data Element	Description	Data Type	Value/Example
`RemainingDriveTimeUntilBreak`	The available driving hours before the drive needs to take a rest break. The format is in seconds.	double	28,800.0
`RemainingDriveTime`	The available driving hours until the end of work day. The format is in seconds.	double	39,600.0
`RemainingOnDutyTime`	The available On-Duty hours available until the end of work day. For Canada HOS this is the available On-Duty hours until the end of the work shift. The format is in seconds.	double	50,400.0
`RemainingCanadaOnDutyTime`	For Canada HOS this is the available On-Duty hours available until the end of work day. The format is in seconds.	double	50,400.0
`RemainingTimeUntilFullDayBreak`	For Canada Cycle Two HOS this is the available hours at origin until a full day (24-hour) break is needed. The format is in seconds.	double	252,000.0
`RemainingCycleDutyTime`	The available Cycle duty time until Cycle reset. The format is in seconds.	double	216,000.0
`CycleTimeGains`	The list of cycle time gains per day. The format is in seconds.		[28800.0, 28800.0, 28800.0, 28800.0, 28800.0, 28800.0]
`LastCycleResetDateTime`	The date and time of the last cycle reset for Canadian hours of service if it occurred on this trip.	string	6/21/2017 07:00:00-0400
`Last24HourBreakDateTime`	The date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service.	string	6/21/2017 07:00:00-0400

HoursOfServiceLocation

Data Element	Description	Data Type	Value/Example
`Type`	Type of stop. Origin - 1, Work - 2, Waypoint - 3, FuelStop - 4, RestStopShort - 5, RestStopLong - 6, RestStopCycleReset - 7, Destination - 9, RendezVous - 12, RestStopFullDay - 13, RestStopDriverSwitch - 14, BorderCrossing - 15, Break - 16, RestStopShortSplittable - 17, RestStopBiWeekly - 18, Unplanned - 19, DailyShiftGapStop - 20, BreakTimeInDay - 21, BreakTimeInWeek - 22	Enum ( StopType )	RestStopShort
`OnDuty`	Indicates if driver is considered on duty at this stop.	bool	false
`EstimatedTimeOfArrival`	The estimated date and time of arrival at this stop.	string	7/10/2017 2:55:28 PM
`EstimatedTimeOfDeparture`	The estimated date and time of departure from this stop.	string	7/10/2017 3:55:28 PM
`TimeZone`	Time zone this stop resides in.	string	EDT
`StopDuration`	the length of time spent at this stop. The format is decimal hours.	double	0.5
`LegDriveTime`	The time required to drive from the previous stop to this stop. The format is decimal hours.	double	5.883
`LegDistance`	The distance from the previous stop to this stop.	double	310.93

Sample Request

{
  "ReportRoutes": [
    {
      "ReportTypes": [
        {
          "__type": "HoursOfServiceReportType:http://pcmiler.alk.com/APIs/v1.0"
        }
      ],
      "RouteId": "Test",
      "ReportingOptions": {
        "UseTollData": true,
        "Language": 0,
        "EstimatedTimeOptions": {
          "ETAETD": 1,
          "DateOption": 0,
          "DateAndTime": null
        },
        "UseTraffic": true
      },
      "Stops": [
        {
          "Address": {
            "StreetAddress": "4 Yawkey Way",
            "City": "Boston",
            "State": "MA",
            "Zip": "08540",
            "County": "Suffolk",
            "Country": null,
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0
          },
          "Coords": null,
          "Region": 4,
          "Label": "Fenway Park",
          "PlaceName": null,
          "Costs": {
            "CostOfStop": 0,
            "HoursPerStop": 0.5,
            "Loaded": true,
            "OnDuty": true,
            "UseOrigin": false
          },
          "IsViaPoint": false
        },
        {
          "Address": {
            "StreetAddress": "1 Citizens Bank Way",
            "City": "Philadelphia",
            "State": "PA",
            "Zip": "19148",
            "County": "Philadelphia",
            "Country": null,
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0
          },
          "Coords": null,
          "Region": 4,
          "Label": "Citizen's Bank Park",
          "PlaceName": null,
          "Costs": {
            "CostOfStop": 0,
            "HoursPerStop": 1.0,
            "Loaded": true,
            "OnDuty": true,
            "UseOrigin": false
          },
          "IsViaPoint": false
        },
        {
          "Address": {
            "StreetAddress": "115 Federal Street",
            "City": "Pittsburgh",
            "State": "PA",
            "Zip": "15212",
            "County": "Allegheny",
            "Country": null,
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0
          },
          "Coords": null,
          "Region": 4,
          "Label": "PNC Park",
          "PlaceName": null,
          "Costs": {
            "CostOfStop": 0,
            "HoursPerStop": 2.0,
            "Loaded": true,
            "OnDuty": true,
            "UseOrigin": false
          },
          "IsViaPoint": false
        }
      ],
      "Options": {
        "VehicleType": 0,
        "RoutingType": 0,
        "HighwayOnly": false,
        "TruckCfg": {
          "Units": 0,
          "Height": "13'6\"",
          "Length": "53'",
          "Width": "96\"",
          "Weight": "80000",
          "Axles": 5,
          "LCV": false
        },
        "HubRouting": false,
        "HoSOptions": {
          "Enabled": true,
          "RemainingDriveTime": 39600.0,
          "RemainingOnDutyTime": 50400.0,
          "CurrentOffDutyTime": 32400.0,
          "RemainingDriveTimeUntilBreak": 28800.0,
          "RemainingCycleDutyTime": 72000.0,
          "HoSRuleType": 0,
          "CycleTimeGains": [
            36000.0,
            50400.0,
            36000.0,
            21600.0,
            50400.0,
            36000.0
          ],
          "TerminalDayStartTime": "12:00:00-0400",
          "UseCycleReset": false,
          "UseCustomPlaces": true,
          "TeamDriving": false,
          "CustomBreakDurations": {
            "ShortBreakDuration": 3600.0,
            "EndOfDutyBreakDuration": 39600.0,
            "CycleResetBreakDuration": 144000.0
          }
        }
      }
    }
  ]
}

Sample Response

[
  {
    "__type": "HoursOfServiceReport:http://pcmiler.alk.com/APIs/v1.0",
    "RouteID": "Test",
    "DriverHoursOfServiceRemaining": {
      "Enabled": true,
      "RemainingDriveTimeUntilBreak": 4500.0,
      "RemainingDriveTime": 4500.0,
      "RemainingOnDutyTime": 4500.0,
      "HoSRuleType": 0,
      "RemainingCycleDutyTime": 191340.0,
      "CycleTimeGains": [50400.0, 36000.0, 21600.0, 50400.0, 36000.0, 39240.0],
      "LastCycleResetDateTime": null,
      "Last24HourBreakDateTime": null
    },
    "Stops": [
      {
        "Address": {
          "StreetAddress": "4 Yawkey Way",
          "City": "Boston",
          "State": "MA",
          "Zip": "02215",
          "County": "Suffolk",
          "Country": null,
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "42.346765",
          "Lon": "-71.098853"
        },
        "Region": 4,
        "Label": "Fenway Park",
        "PlaceName": "Fenway Park",
        "Type": 1,
        "OnDuty": true,
        "EstimatedTimeOfArrival": null,
        "EstimatedTimeOfDeparture": "7/13/2017 8:58:56 AM",
        "TimeZone": "EDT",
        "StopDuration": 0.5,
        "LegDriveTime": 0,
        "LegDistance": 0
      },
      {
        "Address": {
          "StreetAddress": "1 Citizens Bank Way",
          "City": "Philadelphia",
          "State": "PA",
          "Zip": "19148",
          "County": "Philadelphia",
          "Country": null,
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "39.906024",
          "Lon": "-75.168207"
        },
        "Region": 4,
        "Label": "Citizen's Bank Park",
        "PlaceName": "Citizen's Bank Park",
        "Type": 2,
        "OnDuty": true,
        "EstimatedTimeOfArrival": "7/13/2017 3:08:57 PM",
        "EstimatedTimeOfDeparture": "7/13/2017 4:08:57 PM",
        "TimeZone": "EDT",
        "StopDuration": 1,
        "LegDriveTime": 6.15,
        "LegDistance": 310.93
      },
      {
        "Address": {
          "StreetAddress": "59 E Oregon Ave",
          "City": "Philadelphia",
          "State": "PA",
          "Zip": "19148",
          "County": "",
          "Country": null,
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "39.914303",
          "Lon": "-75.149458"
        },
        "Region": 4,
        "Label": "Sunoco 'A' Plus",
        "PlaceName": "Sunoco 'A' Plus",
        "Type": 5,
        "OnDuty": false,
        "EstimatedTimeOfArrival": "7/13/2017 4:17:57 PM",
        "EstimatedTimeOfDeparture": "7/13/2017 5:17:57 PM",
        "TimeZone": "EDT",
        "StopDuration": 1,
        "LegDriveTime": 0.13333333333333333,
        "LegDistance": 2.326
      },
      {
        "Address": {
          "StreetAddress": "Pennsylvania Turnpike",
          "City": "Somerset",
          "State": "PA",
          "Zip": "15501",
          "County": "",
          "Country": null,
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "40.000190",
          "Lon": "-79.044731"
        },
        "Region": 4,
        "Label": "North Somerset Service Plaza, I-76 West",
        "PlaceName": "North Somerset Service Plaza, I-76 West",
        "Type": 6,
        "OnDuty": false,
        "EstimatedTimeOfArrival": "7/13/2017 9:20:57 PM",
        "EstimatedTimeOfDeparture": "7/14/2017 8:20:57 AM",
        "TimeZone": "EDT",
        "StopDuration": 11,
        "LegDriveTime": 4.05,
        "LegDistance": 237.956
      },
      {
        "Address": {
          "StreetAddress": "115 Federal Street",
          "City": "Pittsburgh",
          "State": "PA",
          "Zip": "15212",
          "County": "Allegheny",
          "Country": null,
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "40.447230",
          "Lon": "-80.003980"
        },
        "Region": 4,
        "Label": "PNC Park",
        "PlaceName": "PNC Park",
        "Type": 9,
        "OnDuty": true,
        "EstimatedTimeOfArrival": "7/14/2017 9:35:57 AM",
        "EstimatedTimeOfDeparture": null,
        "TimeZone": "EDT",
        "StopDuration": 2,
        "LegDriveTime": 1.25,
        "LegDistance": 71.847
      }
    ],
    "TotalDrivingDuration": 11.616666666666667,
    "TotalDuration": 27.116666666666667
  }
]

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION