queryType: getExpansionFactors*

The getExpansionFactors queryType is passed to the API to get relevant expansion factors for states and counties filtered by road types and vehicle classes of interest.

Note:

See Special Case APIs for more information.

Expansion factors are returned for all counties overlapping input zones. These expansion factors provide an indication of how Geotab’s observed volume relates to the entire commercial vehicle population in a given area.

Parameters

These parameters should be passed to the functionParameters object regardless of which method you choose to make an API request.

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getExpansionFactors.STRINGgetExpansionFactorsY
requestZoneTypesAn array of strings representing the different zone types you would like to get returned.ARRAY“State” or ”County”Y
roadTypesAn array of strings representing the different road types for which you want data. An empty array means all available road types.ARRAY“all”, “motorway”, ”trunk”, “primary”, “secondary” or “tertiary”N
vehicleGroups

Array of strings representing the vehicle groups for which you would like to retrieve expansion factors.

Passing an empty array will return all vehicle groups.

 ARRAY

  • "Universal": all Geotab vs. market

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

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

N
yearThe year for which you would like expansion factors. Expansion Factors are available for 2022 and 2023.INTEGER2022, 2023Y
zones

An array of objects representing the zones for which you want information. Each object contains:

  • ZoneId (string) – A state id or county

  • ISO_3166_2 (string) – The ISO code of the state or county

  • ZoneType (string) – the type of zone.

ARRAYZoneType - “State“ or “County”. See Zones in Data Dictionary for details on how to structure the zone inputs for each zone type.Y

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONSee here.
500JSONSee here.

Response Schema

AttributeDescriptionData TypeDefined Value Set
ExpansionFactorA discrete multiplier that when applied to Geotab volume counts provides an approximation of market commercial volume.FLOAT-
ExpansionFactorLowerLower bound of the range of expansion factor, inferred using the MAPE from the AADT model for the state and road type.FLOAT-
ExpansionFactorUpperUpper bound of the range of expansion factor, inferred using the MAPE from the AADT model for the state and road type.FLOAT-
ISO_3166_2The state ISO code of the zone.STRING-
IsEstimatedAn indicator of whether the expansion factor has been estimated based on other expansion factors (true), or modeled using AADT data (false).BOOLTrue or False
MAPEThe mean absolute % error between predicted volumes and benchmark market volumes.FLOAT-
MarketShareThe estimated % market share Geotab has in the geography.FLOAT-
RoadTypeThe road type context of the expansion factor.STRING“all”, “motorway”, ”trunk”, “primary”, “secondary”, “tertiary”
VehicleGroupThe vehicle group of the expansion factor.STRING“Universal”, “Medium” or “Heavy”
YearThe year of applicability for the expansion factor.INTEGER“2022”, “2023”
ZoneDescription
Description of the zone when available. The value is based on the type of zone:

  • "State" - state name

  • "County" - county name

STRING-
ZoneIdThe zone ID for which the expansion factor is returned.STRING-
ZoneTypeThe zone type of the zone.STRING“State” or “County”

Sample parameters

{
"includeGeography": false,
"requestZoneTypes":[],
"queryType":"getExpansionFactors",
"roadTypes":[],
"vehicleGroups":[],
"year":2022,
"zones":[{
    			 "ZoneId":"<ZoneId>",
    			 "ISO_3166_2":"<ISO_3166_2>",
    			 "ZoneType":"<ZoneType>"
		}]

}