Start hours of service analytics job

Hours of Service Analytics shows how aggregated metrics for commercial drivers' remaining Hours of Service (HOS) status across required Rest, Drive Time, Daily, and Weekly. Use it to support truck parking siting, safety research, and route planning. Results can be filtered by number of stops in a zone (defaults to 30), minimum or maximum hours of service remaining, or vehicle characteristics. Country, Segment, and RelatedRoad zones are not supported.

Altitude Help Center - Stop Analytics API module

Request Body

Analysis parameters.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`aggregationMode`	integer	-	0, 2, 3	Geographic aggregation mode: 0=road segment, 2=zone, 3=H3.	Y
`dateRanges`	array<object>	dateFrom: string (date); dateTo: string (date)	-	Date ranges to include in the analysis. Maximum 4 non-overlapping ranges; results are aggregated across all ranges. The earliest supported date is April 1, 2026.	Y
`daysOfWeek`	array<integer>	-	1, 2, 3, 4, 5, 6, 7	Days of the week to include (1=Sunday … 7=Saturday). An empty array includes all days.	N
`fuelTypes`	array<string>	-	diesel, electric, flexible, gasoline, hybrid, other, unknown	Fuel types to include. Valid values: diesel, electric, flexible, gasoline, hybrid, other, unknown. An empty array includes all fuel types.	N
`includeGeography`	boolean	-	-	When true, includes GeoJSON geography in the response. Forced true for aggregation mode 3. Defaults to false for all other modes.	N
`industries`	array<string>	-	agriculture, mining, utilities, construction, manufacturing, wholesale, retail, transportation_and_warehousing, information_and_cultural, finance_and_insurance, real_estate, science_and_technology, management, administrative_and_support, education, health_care, arts_and_entertainment, accommodation_and_food, public_administration, other_services, unclassified	Named industry IDs from GET /api/v2/filters/industries (e.g. 'manufacturing', 'retail'). Resolved to NAICS codes at query time and combined with any naics values. Leave both industries and naics empty to include all industries.	N
`maxCellLevel`	integer	-	-	Maximum H3 cell level when aggregationMode is 3. Defaults to 10.	N
`maxHosClockRemaining`	number	-	-	Maximum hours of service clock time remaining (minutes, inclusive) for a stop to count toward the in-threshold stop counts. Defaults to 60 when omitted.	N
`minCellLevel`	integer	-	-	Minimum H3 cell level when aggregationMode is 3. Defaults to 5.	N
`minHosClockRemaining`	number	-	-	Minimum hours of service clock time remaining (minutes, inclusive) for a stop to count toward the in-threshold stop counts. No lower bound when omitted.	N
`minHosStopCount`	integer	-	-	Minimum number of hours of service stops an output zone must have to be included in the results. Defaults to 30 when omitted.	N
`naics`	array<integer>	-	-	Explicit raw NAICS integer codes to filter by. Combined with any industries values. Leave both naics and industries empty to include all industries.	N
`roadTypes`	array<string>	-	living_street, motorway, motorway_link, primary, primary_link, residential, road, secondary, secondary_link, service, tertiary, tertiary_link, trunk, trunk_link, unclassified	Road types to include. Applies only when aggregationMode is 0. Omit or send an empty array to include all road types.	N
`timeFrom`	string	-	-	Start of the time-of-day window (hh:mm:ss or hh:mm:ss.ms). Defaults to 00:00:00 when omitted.	N
`timeTo`	string	-	-	End of the time-of-day window (hh:mm:ss or hh:mm:ss.ms). Defaults to 23:59:59.999 when omitted.	N
`vehicleClassIds`	array<string>	-	-	Vehicle class filter IDs from GET /api/v2/filters/vehicle-classes. IDs must use the scheme_vehicleClassIndex_categoryIndex format and share one scheme; IDs that do not name a known vehicle class are rejected. An empty array includes all vehicle classes.	N
`vehicleClassSchemeId`	integer	-	1, 2, 3, 4, 5, 6	Vehicle classification scheme: 1 = VIUS, 2 = GVWR (FHWA), 3 = Truck Weight Classes, 4 = CARB, 5 = Gross Weight Group (custom scheme), 6 = Expansion Factors (custom scheme). Defaults to 2 when omitted. See GET /api/v2/filters/vehicle-class-schemes.	N
`vehicleClasses`	array<object>	vehicleType: string (values: Truck, Passenger, MPV, Bus, Limo, Other, n/a); weightClass: string (values: *, Class 1, Class 2, Class 3, Class 4, Class 5, Class 6, Class 7, Class 8, Class A, Class B, Class C, Class D, Class E, Class F, Class G, Class H)	-	Vehicle class filters. Use an empty array to include all vehicle classes.	N
`vocations`	array<integer>	-	1, 2, 3, 4, 5	Vocation IDs from GET /api/v2/filters/vocations. An empty array includes all vocations.	N
`zoneIds`	array<string>	-	-	Encoded zone IDs. Country, Segment, and RelatedRoad zones are not supported. Provide either zoneIds or zones, not both.	N
`zones`	array<object>	code: string; iso_3166_2: string; type: string (values: State, County, City, FSA, ZIP, TAZ, CTR, Custom)	-	Zones to include, each identified by a code, a zone type and a state or province code (iso_3166_2). Country, Segment, and RelatedRoad zones are not supported. Provide either zones or zoneIds, not both.	N

Examples

County hours of service request

Zone-level (aggregationMode 2) request for one county.

{
  "aggregationMode": 2,
  "dateRanges": [
    {
      "dateFrom": "2026-04-01",
      "dateTo": "2026-04-30"
    }
  ],
  "zones": [
    {
      "code": "32007",
      "iso_3166_2": "US-NV",
      "type": "County"
    }
  ]
}

Success Responses

202 response: object

Job accepted and queued for processing. Poll the location header URL to check status.

Name	Type	Description
`error`	object	Details about why the job failed (RFC 7807 format), or null if it succeeded.
`id`	string	Unique job identifier.
`links`	object	Navigation URLs for polling and result retrieval.
`status`	string	Current job lifecycle state: PENDING, QUEUED, RUNNING, DONE, FAILED, CANCELED, or NOT_FOUND.

Response Errors

HTTP Status Code	Reason
400	The request body or parameters are invalid.
401	Authentication is required or the provided credentials are invalid.
403	The authenticated user lacks permission to perform this operation.
409	The operation conflicts with the current state of the resource.
422	The request is syntactically valid but semantically cannot be processed.
429	The request rate limit has been exceeded.
500	An unexpected server error occurred.