Hours of Service Report

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.

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 ElementDescriptionData TypePOST Only
EnabledAre hours of service calculations and rest stop insertion enabled.boolFalse
RemainingDriveTimeUntilBreakThe available driving hours at origin before the driver needs to take a rest break. The format is in seconds.doubleFalse
RemainingDriveTimeThe available driving hours at origin until the end of work day. The format is in seconds.doubleFalse
RemainingOnDutyTimeThe 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.doubleFalse
RemainingCanadaOnDutyTimeFor Canada HOS this is the available On-Duty hours at origin until the end of work day. The format is in seconds.doubleTrue
RemainingTimeUntilFullDayBreakFor 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.doubleTrue
HoSRuleTypeThe hours of service rule currently in use. USFed607LH - 0, USFed708LH - 1, CanadaCycle1 - 2, CanadaCycle2 - 3, California808 - 4, Texas707 - 5, USShortHaul - 6.HoSScheduleType ( Enum)False
RemainingCycleDutyTimeThe available Cycle duty time at origin until Cycle reset. The format is in seconds.doubleFalse
CycleTimeGainsAn array of cycle time gains in seconds for the next 6 or 7 days.doubleTrue
LastCycleResetDateTimeThe time of the last cycle reset for Canadian hours of service.stringTrue
Last24HourBreakDateTimeThe date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service.stringTrue
UseCycleResetWhether we do full cycle time reset or not.boolTrue
TerminalDayStartTimeThe time of day used to determine when a 24-hour period defining a ‘day’ starts. The format should be “HH:mm:sszzz”stringTrue
UseCustomPlacesWhether to use custom places for HOS rest stops.boolTrue
TeamDrivingWhether there are team drivers.boolTrue
CustomBreakDurationsThe custom break durations for hours of service rest stops.HoursOfServiceBreakDurationsTrue
AlternateHoSRuleTypeThe 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

HoursOfServiceBreakDurations

Data ElementDescriptionData Type
ShortBreakDurationThe short break duration. The format is in seconds.double
EndOfDutyBreakDurationThe end of duty break duration. The format is in seconds.double
CycleResetBreakDurationThe cycle reset break duration. The format is in seconds.double
DriverSwitchBreakDurationThe driver switch break duration. The format is in seconds.double
BorderCrossingWaitDurationThe border crossing wait duration. The format is in seconds.double

Hours Of Service Report Response

Data ElementDescriptionData TypeValue/Example
typeDescribes the type of report and what it does.stringHoursOfServiceReport
DriverHoursOfServiceRemainingDrivers remaining hours of service at the end of the route.(Can be null)Complex
StopsThe list of all the stops for the trip, including any newly inserted ones, with corresponding departure and arrival times and stop durations.Complex
TotalDrivingDurationTotal drive time duration of the trip. Format is in decimal hours.double
TotalDurationTotal duration of the trip including all stop times. Format is in decimal hours.double

HoursOfServiceRemaining

Data ElementDescriptionData TypeValue/Example
RemainingDriveTimeUntilBreakThe available driving hours before the drive needs to take a rest break. The format is in seconds.double28,800
RemainingDriveTimeThe available driving hours until the end of work day. The format is in seconds.double39,600
RemainingOnDutyTimeThe 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.double50,400
RemainingCanadaOnDutyTimeFor Canada HOS this is the available On-Duty hours available until the end of work day. The format is in seconds.double50,400
RemainingTimeUntilFullDayBreakFor 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.double252,000
RemainingCycleDutyTimeThe available Cycle duty time until Cycle reset. The format is in seconds.double216,000
CycleTimeGainsThe list of cycle time gains per day. The format is in seconds.[28800, 28800, 28800, 28800, 28800, 28800]
LastCycleResetDateTimeThe date and time of the last cycle reset for Canadian hours of service if it occurred on this trip.string6/21/2017 07:00:00-0400
Last24HourBreakDateTimeThe date and time of the last off duty break that was at least 24 consecutive hours for Canadian hours of service.string6/21/2017 07:00:00-0400

HoursOfServiceLocation

Data ElementDescriptionData TypeValue/Example
TypeType of stop. Origin - 1, Work - 2, Waypoint - 3, FuelStop - 4, RestStopShort - 5, RestStopLong - 6, RestStopCycleReset - 7, Destination - 9, RestStopFullDay - 13, RestStopDriverSwitch - 14, BorderCrossing - 15Enum ( StopType)RestStopShort
OnDutyIndicates if driver is considered on duty at this stop.boolfalse
EstimatedTimeOfArrivalThe estimated date and time of arrival at this stop.string7/10/2017 2:55:28 PM
EstimatedTimeOfDepartureThe estimated date and time of departure from this stop.string7/10/2017 3:55:28 PM
TimeZoneTime zone this stop resides in.stringEDT
StopDurationthe length of time spent at this stop. The format is decimal hours.double0.5
LegDriveTimeThe time required to drive from the previous stop to this stop. The format is decimal hours.double5.883
LegDistanceThe distance from the previous stop to this stop.double310.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,
          "RemainingOnDutyTime": 50400,
          "RemainingDriveTimeUntilBreak": 28800,
          "RemainingCycleDutyTime": 72000,
          "HoSRuleType": 0,
          "CycleTimeGains": [36000, 50400, 36000, 21600, 50400, 36000],
          "TerminalDayStartTime": "12:00:00-0400",
          "UseCycleReset": false,
          "UseCustomPlaces": true,
          "TeamDriving": false,
          "CustomBreakDurations": {
            "ShortBreakDuration": 3600,
            "EndOfDutyBreakDuration": 39600,
            "CycleResetBreakDuration": 144000
          }
        }
      }
    }
  ]
}

Sample Response

[
  {
    "__type": "HoursOfServiceReport:http://pcmiler.alk.com/APIs/v1.0",
    "RouteID": "Test",
    "DriverHoursOfServiceRemaining": {
      "Enabled": true,
      "RemainingDriveTimeUntilBreak": 4500,
      "RemainingDriveTime": 4500,
      "RemainingOnDutyTime": 4500,
      "HoSRuleType": 0,
      "RemainingCycleDutyTime": 191340,
      "CycleTimeGains": [50400, 36000, 21600, 50400, 36000, 39240],
      "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
  }
]