Start idle metrics job

Creates a job to generate an idle metrics analysis for the selected zones, date/time filters, industries, and vehicle filters.

Altitude Help Center — getIdleMetrics

Request Body

Idle metrics analysis parameters.

application/json: object

Name	Type	Input Shape	Values	Description	Value Required
`aggregateAllZones`	boolean	-	-	When true, results are aggregated across all selected zones into a single row.	N
`aggregationUnits`	array<string>	-	hour, dayofweek, month	Time-series dimensions to generate when generateTimeSeries is true. Must be one of: hour, dayofweek, month. An empty array generates all three.	N
`dateFrom`	string	-	-	First date of the analysis range, formatted as yyyy-mm-dd.	Y
`dateTo`	string	-	-	Last date of the analysis range (inclusive), formatted as yyyy-mm-dd.	Y
`daysOfWeek`	array<DayOfWeek>	-	1, 2, 3, 4, 5, 6, 7	Days of the week to include (1=Sunday … 7=Saturday). An empty array includes all days.	N
`excludeServiceRoads`	boolean	-	-	When true, service road categories are excluded from results. Defaults to true when omitted.	N
`fuelTypes`	array<FuelType>	-	diesel, electric, flexible, gasoline, hybrid, other, unknown	Fuel types to include. An empty array includes all fuel types.	N
`generateTimeSeries`	boolean	-	-	When true, a time-series breakdown child analysis is generated for each aggregation unit.	Y
`industries`	array<IndustryGroup>	-	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
`isMetric`	boolean	-	-	When true, distance values are returned in kilometres; when false, in miles. Defaults to the isMetric setting on the authenticated user's profile when omitted.	N
`naics`	array<integer (int64)>	-	-	Explicit raw NAICS integer codes to filter by. Combined with any industries values. Leave both naics and industries empty to include all industries.	N
`resultsBySegment`	boolean	-	-	When true, results are broken down by road segment rather than by zone.	N
`roadTypes`	array<RoadType>	-	living_street, motorway, motorway_link, primary, primary_link, residential, road, secondary, secondary_link, service, tertiary, tertiary_link, trunk, trunk_link, unclassified	OSM road types to include. An empty array includes all road types.	N
`timeFrom`	string	-	-	Start of the time-of-day window, formatted as hh:mm:ss.	Y
`timeTo`	string	-	-	End of the time-of-day window, formatted as hh:mm:ss.999.	Y
`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. An empty array includes all vehicle classes.	N
`vehicleClassSchemeId`	integer	-	-	Vehicle classification scheme, from 1 through 5. Defaults to 2 (FHWA/GVWR) when omitted.	N
`vehicleClasses`	array<object>	vehicleType: string; weightClass: string	-	Vehicle class filters. Use an empty array to include all vehicle classes.	N
`vehicleYears`	array<object>	lowerBound: integer (int64); upperBound: integer (int64)	-	Vehicle model-year bins. An empty array includes all model years.	N
`vocations`	array<VocationID>	-	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 ID strings. Provide exactly one of zoneIds or zones (not both).	N
`zones`	array<object>	code: string; iso_3166_2: string; type: string	-	Zone objects with code, type, and iso_3166_2. Provide exactly one of zones or zoneIds (not both).	N

Examples

County idle metrics request

Runs idle metrics for Fulton County, Georgia during weekday daytime hours.

{
  "aggregationUnits": [
    "hour",
    "dayofweek",
    "month"
  ],
  "dateFrom": "2026-01-01",
  "dateTo": "2026-01-31",
  "daysOfWeek": [
    2,
    3,
    4,
    5,
    6
  ],
  "fuelTypes": [
    "diesel",
    "gasoline"
  ],
  "generateTimeSeries": true,
  "industries": [
    "transportation_and_warehousing"
  ],
  "isMetric": false,
  "timeFrom": "07:00:00",
  "timeTo": "18:59:59.999",
  "vehicleClasses": [
    {
      "vehicleType": "Truck",
      "weightClass": "Class 3"
    },
    {
      "vehicleType": "Truck",
      "weightClass": "Class 8"
    }
  ],
  "zones": [
    {
      "code": "13121",
      "iso_3166_2": "US-GA",
      "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.