queryType: getModeledVehicleDistanceTraveled*

The getModeledVehicleDistanceTraveled queryType is passed to the API to return expanded vehicle distance traveled (VMT/VKT), expanded by county-level expansion factors.

Note:

See Special Case APIs for more information.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getModeledVehicleDistanceTraveled.STRINGgetModeledVehicleDistanceTraveledY
aggregateAllZonesWhether to aggregate the results over all zones (true) or report the results for each zone provided (false). The default is false.BOOLtrue or falseN
aggregationUnits

Array of requested time series aggregation units to be included in time series breakdowns. This attribute determines which time series breakdowns are generated if generateTimeSeries is set to true. Supported values (not case-sensitive) are:

  • hour - for a breakdown by hour from 0 to 23.

  • daytype - for a breakdown by day-of-week, where “Weekend” = [1,7] or Saturday through Sunday, and “Weekday” = [2,3,4,5,6] or Monday through Friday.

  • daytypehour - for a breakdown by day type (“Weekend”, “Weekday”) and hour from 0 to 23.

The default is [“hour”, “daytype”, “daytypehour”].

Note: An empty array will return all available time series.
ARRAY

“hour”,

“daytype”,

“daytypehour”

N
dateRange
An object defining the analysis date range. Each object contains: DateFrom (string) - first date in the analysis date range formatted as "yyyy-mm-dd". DateTo (string) - last date in the analysis date range formatted as "yyyy-mm-dd".
Note:

Limited to dates between January 1, 2022, and December 31, 2022.

OBJECT-Y
daysOfWeekArray of integers representing each week day. Can send an empty array to return all days.ARRAY[1,7] (1 = Sunday, 2 = Monday, etc.)N
generateTimeSeries

An indicator of whether to generate a time series breakdown (true) or not (false) as a child analysis. Time series will be generated for each time aggregation in aggregationUnits.

Note:

The time series breakdown results can be retrieved using the getSavedResults API. See How to Retrieve Time Series Results .

BOOLEANtrue or falseY
isMetricTrue for data to be returned in metric units, false for imperial.BOOLEANtrue or falseY
timeRange

An object representing the analysis time range. Each object contains: TimeFrom (string) - start of the time range formatted as "hh:mm:ss.ms" string. TimeTo (string) - end of the time range formatted as "hh:mm:ss.ms" string. The default is “00:00:00” to “23:59:59.999”.

OBJECT-Y
zones

An array of objects representing the zones for which you want information. Each object contains ZoneId, ISO_3166_2, and ZoneType:

  • ZoneId (string) – A custom zone ID, segment ID, related road ID or a standard zone ID such as county ID, city ID, etc.

  • ISO_3166_2 (string) – The ISO code of the standard zone. Does not apply to custom zones, segments or related roads and can be set to null.

  • ZoneType (string) – the type of zone (see Defined Value Set column).
    Note:

    Restricted to US zones only.

ARRAY

ZoneType - “Custom”, “State”, “County”, “City”, “TAZ”, “ZIP” or “CTR”.

See Zones for details on how to structure the zone inputs for each zone type.

Y

Response Schema

AttributeDescriptionData TypeDefined Value Set
DistanceByVehicleGroup
Array of objects representing the observed and modeled distance for each vehicle group. Each object contains: VehicleGroup (string) - vehicle group name. Distance (float) - the total observed distance traveled (miles or kilometers) for the zone. ModeledDistance (float) - total expanded observed distance traveled, expanded by county-level expansion factors (RoadType = “All”; VehicleGroup = <VehicleGroup>).
Note:

Expansion factor applied to a segment based on the segment geospatially tagged countyId.

ARRAY

VehicleGroup -

Universal : All Geotab vs. market, including both commercial and non-commercial vehicles.

Heavy : GVWR 7-8 vs. equivalent commercial market.

Medium : GVWR 3-6 vs. equivalent commercial market.

ISO_3166_2
The ISO 3166:2 code of the zone.
Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING-
ZoneDescription
Description of the zone when available. The is based on the type of zone: “State” - state name,“County” - county name,“City” - city name,“CTR” - census tract description, “Segment” - road name, if available,“Custom” - custom zone name.
Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING-
ZoneId
The zone ID for which the data is returned.
Note:

If aggregateAllZones is set to true, this value will be “All zones aggregated”.

STRING-
ZoneType
The zone type of the zone.
Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING“Custom”, “Segment”, “State”, “County”, “City”, “TAZ”, “ZIP” or “CTR”

Time Series Response Schema

This breakdown result is only created if generateTimeSeries value is set to true. The time series breakdown results can be retrieved using the getSavedResults API. See for more details.

AttributeDescriptionData TypeDefined Value Set
AggregationUnitThe time based unit by which to aggregate data.STRING

  • “Hour”

  • “DayOfWeek”

  • “Month”

AggregationValue

The associated AggregationUnit value. The value set is based on the AggregationUnit value. Value format based on AggregationUnit:

  • hour - number of the hour based on 24 hour, e.g. 1 or 16

  • dayofweek - numeric value for day of week where Sunday is 1 and Saturday is 7

  • month - number of the month, e.g. 1 or 12

DistanceByVehicleGroup

Array of objects representing the observed and modeled distance for each vehicle group. Each object contains:

  • VehicleGroup (string) - vehicle group name.

  • Distance (float) - the total observed distance traveled (miles or kilometers) for the zone.

  • ModeledDistance (float) - total expanded observed distance traveled, expanded by county-level expansion factors (RoadType = “All”; VehicleGroup = <VehicleGroup>).

Expansion factor applied to a segment based on the segment geospatially tagged countyId.

ARRAY

VehicleGroup -

Universal: All Geotab vs. market, including both commercial and non-commercial vehicles.

Heavy: GVWR 7-8 vs. equivalent commercial market.

Medium: GVWR 3-6 vs. equivalent commercial market.
ISO_3166_2

The ISO 3166:2 code of the zone.

Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING-
ZoneDescription

Description of the zone when available. The is based on the type of zone:

“State” - state name

“County” - county name

“City” - city name

“CTR” - census tract description

“Segment” - road name, if available

“Custom” - custom zone name

Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING-
ZoneId

The zone ID for which the data is returned.

Note:

If aggregateAllZones is set to true, this value will be "All zones aggregated".

STRING-
ZoneType

The zone type of the zone.

Note:

If aggregateAllZones is set to true, this value will be an empty string.

STRING“Custom”, “Segment”, “State”, “County”, “City”, “TAZ”, “ZIP” or “CTR”

Sample parameters

Sample parameters that should go inside your functionParameters object

{
	"aggregateAllZones": false,
	"aggregationUnits":[],
	"dateRange": {
				"DateFrom": "<YYYY-MM-DD>",
				"DateTo": "<YYYY-MM-DD>"
			},
	"daysOfWeek": [],
       "generateTimeSeries": false,
	"isMetric": true,
	"timeRange": {
				"TimeFrom": <TimeFrom>,
				"TimeTo": <TimeTo>
			},
	"queryType": "getModeledVehicleDistanceTraveled",
	"zones": [
			{
				"ZoneId": "<ZoneId>",
				"ISO_3166_2": "<ISO_3166_2>",
				"ZoneType": "<ZoneType>",
			}
		   ]
}