queryType: getFuelPointAnalytics

The getFuelPointAnalytics queryType returns refuel detection data, allowing users to understand trends in refuelling events and get contextual information regarding fuel events including vehicle class, vehicle vocation, and vehicle industry.

The getFuelPointAnalytics queryType is passed to the API to retrieve refuel detection data for the specified zones and date ranges.

Parameters

These parameters should be passed to the functionParameters object in your API request.

ParameterDescriptionTypeDefined Value SetValue Required
queryTypeMust equal "getFuelPointAnalytics".STRING"getFuelPointAnalytics"Y
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.

  • dayofweek — 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.

  • month — for breakdown by month from 1 to 12.

Default returns all aggregation options.

Note:

An empty array will return all available time series.

ARRAY"hour", "dayofweek", "month"N
dateRanges

An array of objects representing the date ranges of interest. 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:

Analysis outputs will be aggregated and returned over all date ranges combined. No default. Omitting this parameter will return an error.

ARRAY-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
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
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 the getIndustries API. Default returns all NAICS codes.

INTEGER-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".

  • TimeTo (string) — end of the time range formatted as "hh:mm:ss.ms".

The default is "00:00:00" to "23:59:59.999".

OBJECT-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
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
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. Default returns all vocations.

ARRAYSee Vocations 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 (string) — The custom zone ID.

  • ISO_3166_2 (string) — the ISO code of the standard zone. Does not apply to custom zones and can be set to null.

  • ZoneType (string) — the type of zone.

ARRAYZoneType: "Custom". See Zones for details on how to structure zone inputs for each zone type.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 Altitude Support for assistance.

Response Schema

DailyRefuelCountAvg

The average daily number of refuels.

Note:

The denominator for this calculation is the number of days within the analysis period that have non-zero refuels.

FLOAT-
ISO_3166_2The ISO 3166:2 code for the state or province associated with the output zone, where available.STRING-
RefuelCountThe number of refuel events occurring at the stop location.INTEGER-
RefuelMetricsByFuelType

Array of objects representing refuel metrics for each fuel type. Each object contains:

  • FuelType (string) — fuel type name.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByIndustry

Array of objects representing refuel metrics for each NAICS code 1. Each object contains:

  • NAICS_Code_1 (integer) — NAICS code 1.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByVehicleClass

Array of objects representing refuel metrics 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.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByVocation

Array of objects representing refuel metrics for each vocation. Each object contains:

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

  • Vocation (string) — vocation name.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
StopCountThe number of stop events occurring at the stop location.INTEGER-
VehicleCountThe number of unique refuelling vehicles.INTEGER-
ZoneDescriptionThe custom zone name.STRING-
ZoneIdThe zone ID for which the data is returned.STRING-
ZoneTypeThe zone type of the zone.STRING"Custom"

Sample parameters

{
    "queryType": "getFuelPointAnalytics",
    "aggregationUnits": ["hour"],
    "dateRanges": [{
        "DateFrom": "2025-06-01",
        "DateTo": "2025-06-30"
    }],
    "generateTimeSeries": true,
    "timeRange": {"TimeFrom": "00:00:00", "TimeTo": "23:59:59.999"},
    "zones": [{
        "ZoneId": "xx-xxxxxxxxxxxx",
        "ISO_3166_2": "US-NV",
        "ZoneType": "Custom"
    }]
}

Time Series Response Schema

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

AggregationUnitThe time-based unit by which to aggregate data.STRING"hour", "dayofweek", "month"
AggregationValue

The associated AggregationUnit value. Value format based on AggregationUnit:

  • hour — number of the hour based on 24-hour format, 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-
DailyRefuelCountAvg

The average daily number of refuels.

Note:

The denominator for this calculation is the number of days that have refuels.

FLOAT-
ISO_3166_2The ISO 3166:2 code for the state or province associated with the output zone, where available.STRING-
RefuelCountThe number of refuel events occurring within the input zone.INTEGER-
RefuelMetricsByFuelType

Array of objects representing refuel metrics for each fuel type. Each object contains:

  • FuelType (string) — fuel type name.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByIndustry

Array of objects representing refuel metrics for each NAICS code 1. Each object contains:

  • NAICS_Code_1 (integer) — NAICS code 1.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByVehicleClass

Array of objects representing refuel metrics 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.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
RefuelMetricsByVocation

Array of objects representing refuel metrics for each vocation. Each object contains:

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

  • Vocation (string) — vocation name.

  • RefuelCount (integer) — number of refuels.

  • StopCount (integer) — number of stops.

  • VehicleCount (integer) — number of refuelling vehicles.

ARRAY-
StopCountThe number of stop events occurring at the stop location.INTEGER-
VehicleCountThe number of unique refuelling vehicles.INTEGER-
ZoneDescriptionThe custom zone name.STRING-
ZoneIdThe zone ID for which the data is returned.STRING-
ZoneTypeThe zone type of the zone.STRING"Custom"