queryType: getVehicleDistanceTraveled*
The getVehicleDistanceTraveled queryType is passed to the API to get the observed vehicle distance traveled for a geography of interest.
See Special Case APIs for more information.
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
| Parameter | Description | Type | Defined Value Set | Value Req'd |
|---|---|---|---|---|
| queryType | Must equal getRegionalTravelMetrics. | STRING | getRegionalTravelMetrics | Y |
| aggregateAllZones | Whether to aggregate the results over all zones (true) or report the results for each zone provided (false). The default is false. | BOOL | true or false | N |
| 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
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: | OBJECT | - | Y |
| daysOfWeek | Array of integers representing each week day. Can send an empty array to return all days. | ARRAY | [1,7] (1 = Sunday, 2 = Monday, etc.) | N |
| excludeServiceRoads | True 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 Note:
A null in | ARRAY | - | N |
| fuelTypes | An 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. | ARRAY | See 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 | BOOLEAN | true or false | Y |
| isMetric | True for data to be returned in metric units, false for imperial. | BOOLEAN | true or false | Y |
| NAICS | An 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 |
| roadTypes | Array of strings representing the different road types for which you want data. Empty array means all road types. | ARRAY | List of OSM road types. See the Road Types table. | N |
| timeRange |
An object representing the analysis time range. Each object contains: | OBJECT | - | Y |
| vehicleClassSchemeId | Determines 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 | 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 Note:
A null in For example: [{"LowerBound": 2017, "UpperBound": 2020}, {"LowerBound":2021, "UpperBound": 2022}] will produce 3 objects in the | ARRAY | Supported vehicle years: 1996-2025 | N |
| vocations | An array of integers representing vocation IDs for vocations of interest. Can pass specific IDs or an empty array to return data for all vocations. | ARRAY | See 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
Learn more about Zones in the Data Dictionary. | ARRAY |
| Y |
Responses
| Code | Type | Description |
|---|---|---|
| 200 | JSON | The requested data. |
| 401 | JSON | Occurs for various unauthorized tasks, such as not providing credentials in your parameters. |
| 500 | JSON | Occurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs. |
Response Schema
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| Distance | The 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: | ARRAY | - |
| DistanceByFuelType |
Array of objects representing the distance, trip count and vehicle counts for each fuel type. Each object contains: | ARRAY | - |
| DistanceByIndustry |
Array of objects representing the distance, trip count and vehicle counts for each NAICS code 1. Each object contains: | ARRAY | - |
| DistanceByRoadType |
Array of objects representing the distance, trip count and vehicle counts for each road type. Each object contains: | ARRAY | - |
| DistanceByVehicleClass |
Array of objects representing the distance, trip count and vehicle counts for each vehicle class. Each object contains: | ARRAY | - |
| DistanceByVehicleYear |
Array of objects representing the distance, trip count and vehicle counts for each vehicle year bucket. Each object contains: | ARRAY | - |
| DistanceByVocation |
Array of objects representing the distance, trip count and vehicle counts for each vocation. Each object contains: | ARRAY | - |
| ISO_3166_2 | The ISO 3166:2 code of the zone. | STRING | - |
| TripCount | The total number of trips in the zone. | INTEGER | - |
| TripCountTotal | The total number of trips in the analysis. | INTEGER | - |
| VehicleCount | The total number of unique vehicles in the analysis. | INTEGER | - |
| VehicleCountTotal | The 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 | - |
| ZoneId | The zone id for which the data is returned. | STRING | - |
| ZoneType | The 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.
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| AggregationUnit | The time based unit by which to aggregate data. | STRING |
|
| AggregationValue |
The associated
| STRING | - |
| Distance | The 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:
| ARRAY | - |
| DistanceByVehicleClass |
Array of objects representing the distance, trip count and vehicle counts for each vehicle class. Each object contains:
| ARRAY | - |
| DistanceByVocation |
Array of objects representing the distance, trip count and vehicle counts for each vocation. Each object contains:
| ARRAY | - |
| ISO_3166_2 | The ISO 3166:2 code of the zone. | STRING | - |
| TripCount | The total number of trips in the analysis. | INTEGER | - |
| VehicleCount | The total number of unique vehicles in the analysis. | INTEGER | - |
| ZoneDescription |
Description of the zone when available. The is based on the type of zone:
| STRING | - |
| ZoneId | The zone id for which the data is returned. | STRING | - |
| ZoneType | The 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"
}]
}