queryType: getFuelEconomy*

The getFuelEconomy queryType is passed to the API to get the observed fuel economy for different vehicle classes by geography.

Note:

See Special Case APIs for more information.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getFuelEconomy.STRINGgetFuelEconomyY
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
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:

A minimum date range of 1 month is required.

OBJECT-Y
isMetricTrue for data to be returned in metric units, false for imperial.BOOLEANtrue or falseY
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 FuelEconomyByVehicleYear 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 FuelEconomyByVehicleYear field for 2017-2020, 2021-2022 and all others.

ARRAY-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.

ARRAY

  • ZoneType - “State”

  • “County”

  • “City”

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
CategoryIndexIdentifier for the vehicle class category.INTEGER-
ISO_3166_2The state ISO code of the returned zone.STRING-
FuelEconomyCalculated fuel economy (mph or l/100km).FLOAT-
FuelEconomyByFuelType

Array objects representing the fuel economy for each fuel type. Each object contains:

  • FuelType (string) - the fuel type.

  • FuelEconomy (float) - the calculated fuel economy value (mpg or l/100km).

ARRAY-
FuelEconomyByVehicleYear

Array objects representing the fuel economy for a 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.

  • FuelEconomy (float) - the calculated fuel economy value (mpg or l/100km).

ARRAY-
SchemeIdUnique identifier for the vehicle class scheme. See Vehicle class schemas for more detailed information.INTEGER[1,4]
VehicleClassThe vehicle class for which the data is returned.STRING-
VehicleClassIndexUnique identifier for the vehicle class.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

STRING-
ZoneIdThe zoneId for the zone result represented in the current row.STRING-
ZoneTypeThe zone type of the zone.STRING“State”, ”County” or ”City”

Sample parameters

{
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-31"},
"isMetric":false,
"queryType":"getFuelEconomy",
"vehicleClassSchemeId":2,
"vehicleClasses": [],
"zones":[{
    "ZoneId":"32003",
    "ISO_3166_2":"US-NV",
    "ZoneType":"County"
	}]

}