queryType: getVehicleDistanceTraveled*

The getVehicleDistanceTraveled queryType is passed to the API to get the observed vehicle distance traveled for a geography of interest.

Note:

See Special Case APIs for more information.

Note:

The distance is calculated based only from vehicles that have traveled on the road network. Off-road travel such as on oilfields or on private land, as well as partial road traversals, is not included.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getRegionalTravelMetrics.STRINGgetRegionalTravelMetricsY
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".

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
excludeServiceRoadsTrue to exclude service roads, false to include them. Defaults to true.BOOLEAN-N
fleetSizes

Array of objects representing bin definitions for histogram of fleet size of the vehicle classes selected. There should be an object for each desired bin for DistanceByFleetSize output attribute. Each object contains: LowerBound (integer) - lower bound of the bucket. UpperBound (integer) - upper bound of the bucket.

Note:

A null in LowerBound will be treated as 1 and a null in UpperBound will be treated as no upper bound.

ARRAY-N
fuelTypesAn array of strings representing the fuel types you want analyzed. Possible values are "Diesel", "Electric", "Flexible", "Gasoline", "Hybrid", "Other" and "Unknown". Refer to the Fuel types table for a description of each option. Can send an empty array to return all fuel types.ARRAYSee Fuel types for a list of fuel types-
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
NAICSAn array of integers representing industry IDs. Can pass an empty array to return data for all industries. To get a list of available industries use getIndustries API.ARRAY-N
roadTypesArray of strings representing the different road types for which you want data. Empty array means all road types.ARRAYList of OSM road types. See the Road Types table.N
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
vehicleClassSchemeIdDetermines which vehicle classification scheme you will receive data for. See the Vehicle class schemas for a list of options. The default value is 2.INTEGER[1,4]N
vehicleClasses

An array of vehicle class objects where each object contains VehicleType and WeightClass. To get the list of possible vehicle types and weight classes, refer to Vehicle types and Weight class tables. If a vehicle type does not have any weight classes listed, just pass "*". More information on vehicle classes can be found at AFDC Vehicle Categories. To get all vehicle classes returned, pass an empty array.

ARRAY

See the Vehicle types and Weight class tables.

For Vehicle Type: "Truck", "Passenger", "MPV", "Bus", "Other". More information at AFDC Vehicle Categories.

To get all vehicle types, pass an empty array.

N
vehicleYears

Array of objects representing bin definitions for histogram of vehicle years of the vehicle classes selected. There should be an object for each desired bin for the DistanceByVehicleYear output attribute. Each object contains: LowerBound (integer) - lower bound of the bucket. UpperBound (integer) - upper bound of the bucket.

Note:

A null in LowerBound will be treated as 1 and a null in UpperBound will be treated as no upper bound.

For example: [{"LowerBound": 2017, "UpperBound": 2020}, {"LowerBound":2021, "UpperBound": 2022}] will produce 3 objects in the DistanceByVehicleYear field for 2017-2020, 2021-2022 and all others.

ARRAYSupported vehicle years: 1996-2025N
vocationsAn array of integers representing vocation IDs for vocations of interest. Can pass specific IDs or an empty array to return data for all vocations.ARRAYSee Vocation descriptions for a list of vocation IDs and their mapping information.N
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, a segment 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).

Learn more about Zones in the Data Dictionary.

ARRAY
  • ZoneType - “Custom”

  • “Segment”

  • “State”

  • “County”

  • “City”

  • “TAZ”

  • “ZIP”

  • “CTR”

  • “FSA”

Y

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks, such as not providing credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs.

Response Schema

AttributeDescriptionData TypeDefined Value Set
DistanceThe distance traveled by all the vehicles in the analysis (miles or kilometers).FLOAT-
DistanceByFleetSize

Array of objects representing the distance, trip count and vehicle counts for each fleet size bucket. Each object contains: FleetSize (string) - a string representation of the fleet size bucket. LowerBound (integer) - the lower bound year. UpperBound (integer) - the upper bound year. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByFuelType

Array of objects representing the distance, trip count and vehicle counts for each fuel type. Each object contains: FuelType (string) - fuel type name. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByIndustry

Array of objects representing the distance, trip count and vehicle counts for each NAICS code 1. Each object contains: NAICS_Code_1 (integer) - NAICS code 1. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByRoadType

Array of objects representing the distance, trip count and vehicle counts for each road type. Each object contains: RoadType (string) - road type name. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByVehicleClass

Array of objects representing the distance, trip count and vehicle counts for each vehicle class. Each object contains: SchemeId (integer) - vehicle class scheme identifier. CategoryIndex (integer) - vehicle class category identifier. VehicleClassIndex (integer) - vehicle class identifier. VehicleClass (string) - vehicle class name. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByVehicleYear

Array of objects representing the distance, trip count and vehicle counts for each vehicle year bucket. Each object contains: VehicleYear (string) - a string representation of the vehicle year bucket. LowerBound (integer) - the lower bound year. UpperBound (integer) - the upper bound year. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
DistanceByVocation

Array of objects representing the distance, trip count and vehicle counts for each vocation. Each object contains: VocationId (integer) - unique identifier for the vocation. Vocation (string) - vocation name. TripCount (integer) - number of unique trips that passed through the zone. VehicleCount (integer) - number of vehicles. Distance (float) - the total distance traveled (miles or kilometers).

ARRAY-
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
TripCountThe total number of trips in the zone.INTEGER-
TripCountTotalThe total number of trips in the analysis.INTEGER-
VehicleCountThe total number of unique vehicles in the analysis.INTEGER-
VehicleCountTotalThe total number of unique vehicles in the analysis.INTEGER-
ZoneDescription

Description of the zone when available. The value 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.

STRING-
ZoneIdThe zone id for which the data is returned.STRING-
ZoneTypeThe zone type of the zone. STRING“Custom”, “Segment”, “State”, “County”, “City”, “TAZ”, “ZIP”, “CTR”, or “FSA”

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 How to Retrieve Time Series Results 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

STRING-
DistanceThe distance traveled by all the vehicles in the analysis (miles or kilometers).FLOAT-
DistanceByFuelType

Array of objects representing the distance, trip count and vehicle counts for each fuel type. Each object contains:

  • FuelType (string) - fuel type name.

  • TripCount (integer) - number of unique trips that passed through the zone.

  • VehicleCount (integer) - number of vehicles.

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

ARRAY-
DistanceByVehicleClass

Array of objects representing the distance, trip count and vehicle counts for each vehicle class. Each object contains:

  • SchemeId (integer) - vehicle class scheme identifier.

  • CategoryIndex (integer) - vehicle class category identifier.

  • VehicleClassIndex (integer) - vehicle class identifier.

  • VehicleClass (string) - vehicle class name.

  • TripCount (integer) - number of unique trips that passed through the zone.

  • VehicleCount (integer) - number of vehicles.

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

ARRAY-
DistanceByVocation

Array of objects representing the distance, trip count and vehicle counts for each vocation. Each object contains:

  • VocationId (integer) - unique identifier for the vocation.

  • Vocation (string) - vocation name.

  • TripCount (integer) - number of unique trips that passed through the zone.

  • VehicleCount (integer) - number of vehicles.

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

ARRAY-
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
TripCountThe total number of trips in the analysis.INTEGER-
VehicleCountThe total number of unique vehicles in the analysis.INTEGER-
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

STRING-
ZoneIdThe zone id for which the data is returned.STRING-
ZoneTypeThe zone type of the zone.STRING“Custom”, “State”, “County”, “City”, “TAZ”, “ZIP”, “CTR”, or “FSA”

Sample parameters

Sample parameters that should go inside your functionParameters object

{
"aggregationUnit":true,
"aggregateAllZones":false,
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"},
"excludeServiceRoads":true,
"fleetSizes": [
    {
    "LowerBound":1,
    "UpperBound":100
    },
    {
    "LowerBound":101,
    "UpperBound":1000
    }
],
"generateTimeSeries":false,
"isMetric":false,
"queryType":"getRegionalTravelMetrics",
"roadTypes":['motorway'],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"vehicleClassSchemeId": 2,
"vehicleClasses":[{
    "VehicleType":"Truck",
    "WeightClass":"Class 8"
}],
"zones":[{
    "ZoneId":"32003",
    "ISO_3166_2":"US-NV",
    "ZoneType":"County"
	}]

}