queryType: getDemandGeneration

The getDemandGeneration queryType is passed to the API to understand how much traffic an area of interest either demands or generates.

Note:

See Special Case APIs for more information.

This queryType will return the number of trips that started and ended in the area of interest as well as some basic characteristics about those trips.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getDemandGeneration.STRINGgetDemandGenerationY
aggregateAllZonesWhether to aggregate the results over all zones (true) or report the results for each zone provided (false). The default is false.BOOLEANtrue 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
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 unless you input true for isTrendAnalysis where we will return results per date range.

ARRAY

Maximum of 4 date ranges.

Total coverage across all date ranges may not exceed 1 year or 366 days

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
isMetricTrue for data to be returned in metric units, false for imperial.BOOLEANtrue or falseY
isTrendAnalysisPass true if you want your results grouped based on the dateRanges parameter. For example, if you pass 4 date ranges and this is set to true, you will get 4 sets of results, one for each date range. The default is false.BOOLEANtrue or falseN
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
percentilesArray of integers representing what percentiles you want the metrics broken up into. Default if not provided is [15,50,85].ARRAY-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
vocationsAn array of vocation IDs representing the vocations of interest. Can pass specific IDs or an empty array to return data for all vocations.ARRAYSee this link 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.

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
AggregationDateRanges

Array of objects representing the date ranges utilized for the aggregated metrics. 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".
ARRAY-
DemandByFuelType

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

  • FuelType (string) - the fuel type.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
DemandByIndustry

Array objects representing the demand metrics for each industry. Each object contains:

  • NAICS_Code_1 (integer) - NAICS code 1.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
DemandByVehicleClass

Array objects representing the demand 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.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
DemandByVocation

Array objects representing the demand metrics for each vehicle class. Each object contains:

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

  • Vocation (string) - vocation name.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
TripEndCountThe total number of trips in the analysis that ended in the zone.INTEGER-
TripEndDistancePercentiles

Array of objects representing percentile trip distances for trips that end in the zone, for all input percentiles. Each object contains:

  • Percentile (integer): the percentile value.

  • Value (float): the calculated percentile spot speed value (mph or km/h).

Note:

If no percentiles are input, the 15th and 85th percentiles are provided by default.

ARRAY-
TripStartCountThe total number of trips in the analysis that started in the zone.INTEGER-
TripStartDistancePercentiles

Array of objects representing percentile trip distances for trips that start in the zone, for all input percentiles. Each object contains:

  • Percentile (integer): the percentile value.

  • Value (float): the calculated percentile spot speed value (mph or km/h).

Note:

If no percentiles are input, the 15th and 85th percentiles are provided by default.

ARRAY-
ZoneDescription

Description of the zone when available. The value is based on the zone type:

  • “State” - state name

  • “County” - county name

  • “City” - city name

  • “CTR” - census tract description

  • “Custom” - custom zone name

  • “Segment” - road name, if available

STRING-
ZoneIdThe zoneId for the zone result represented in the current row.STRING-
ZoneTypeThe type of the zone.STRING“State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Custom” or “Segment”

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
AggregationDateRanges

Array of objects representing the date ranges utilized for the aggregated metrics. 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".
ARRAY-
AggregationUnitThe time based unit by which to aggregate data.STRING

  • “hour”

  • “dayofweek”

  • "daytype"

  • “daytypehour"

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

  • daytype - string for the day type [“Weekend” ,“Weekday”]

  • daytypehour - string for day type and hour consolidated e.g. “Weekday_22”

STRING-
DemandByFuelType

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

  • FuelType (string) - the fuel type.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
DemandByVehicleClass

Array objects representing the demand 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.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
DemandByVocation

Array objects representing the demand metrics for each vehicle class. Each object contains:

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

  • Vocation (string) - vocation name.

  • TripStartCount (integer) - the count of trips that start in the zone.

  • TripEndCount (integer) - the count of trips that end in the zone.

  • TripStartDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips starting in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

  • TripEndDistancePercentiles (array of objects) - an array of objects representing distance percentiles of trips ending in the zone, for each input percentile and the fuel type. Each object contains:

    • Percentile (integer)

    • Value (float)

ARRAY-
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
TripEndCountThe total number of trips in the analysis that ended in the zone.INTEGER-
TripEndDistancePercentiles

Array of objects representing percentile trip distances for trips that end in the zone, for all input percentiles. Each object contains:

  • Percentile (integer): the percentile value.

  • Value (float): the calculated percentile spot speed value (mph or km/h).

Note:

If no percentiles are input, the 15th and 85th percentiles are provided by default.

ARRAY-
ZoneDescription

Description of the zone when available. The value is based on the zone type:

  • “State” - state name

  • “County” - county name

  • “City” - city name

  • “CTR” - census tract description

  • “Custom” - custom zone name

  • “Segment” - road name, if available

STRING-
ZoneIdThe zoneId for the zone result represented in the current row.STRING-
ZoneTypeThe type of the zone.STRING

  • “State”

  • ”County”

  • ”City”

  • ”CTR”

  • ”ZIP”

  • “TAZ”

  • “FSA”

  • “Custom”

  • “Segment”

Sample parameters

{
"aggregationUnits": ["hour"]
"dateRanges":[{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"}], 
"generateTimeSeries": false,
"isMetric":false,
"queryType":"getDemandGeneration",
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"zones":[{
    "ZoneId":"32003", 
    "ISO_3166_2":"US-NV", 
    "ZoneType":"County"
	}]
}