Start modeled vehicle distance traveled job

Creates a job to generate a modeled vehicle distance traveled analysis. Uses Geotab's statistical modelling to extrapolate distance traveled estimates for the broader commercial vehicle population beyond connected vehicles, broken down by vehicle class. Set generateTimeSeries to true to produce time-series breakdowns.

Altitude Help Center — getModeledVehicleDistanceTraveled

Request Body

Modeled VDT 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, week, month, daytype, daytypehour, hourofday, day	Time-series dimensions to generate when generateTimeSeries is true. An empty array generates all available units.	N
`dateFrom`	string (date)	-	-	First date of the analysis range, formatted as yyyy-mm-dd.	Y
`dateTo`	string (date)	-	-	Last date of the analysis range (inclusive), formatted as yyyy-mm-dd.	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
`generateTimeSeries`	boolean	-	-	When true, a time-series breakdown is also generated for each aggregation unit. Results are retrievable via GET /api/v2/regional-travel-metrics/modeled-vehicle-distance-traveled/{id}/time-series once the job is complete. Defaults to false when omitted.	N
`isMetric`	boolean	-	-	When true, distance values are returned in kilometres; when false, in miles. Defaults to the unit setting in your user profile when omitted.	N
`timeFrom`	string	-	-	Start of the time-of-day window, formatted as hh:mm:ss. Defaults to 00:00:00 when omitted.	N
`timeTo`	string	-	-	End of the time-of-day window, formatted as hh:mm:ss.999. Defaults to 23:59:59.999 when omitted.	N
`zoneIds`	array<string>	-	-	Zones to include, as encoded zone IDs. Provide exactly one of zoneIds or zones (not both).	N
`zones`	array<object>	code: string; iso_3166_2: string; type: string (values: State, County)	-	Zones to include, each identified by a code, a zone type and a state or province code (iso_3166_2). Provide exactly one of zones or zoneIds (not both).	N

Examples

County modeled VDT request

Translated from the v1 getModeledVehicleDistanceTraveled sample.

{
  "dateFrom": "2025-01-01",
  "dateTo": "2025-01-31",
  "generateTimeSeries": false,
  "isMetric": false,
  "timeFrom": "00:00:00",
  "timeTo": "23:59:59.999",
  "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.