queryType: getObservedCounts*

The getObservedCounts queryType is passed to the API to get the observed counts of vehicle passes and unique vehicles for a given geography per road segment.

Note:

See Special Case APIs for more information.

These counts are broken down by vehicle class, industry, fuel type and vocation and temporal aggregation periods.

Use the getObservedCounts API call to show the specific number of vehicle passes over a road segment. To get trip counts within a zone, use the getDemandGeneration API call to get the number of trips starting or ending in a zone of interest.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getObservedCounts.STRINGgetObservedCountsY
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
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
isDirectionalFalse means we ignore the direction of the road segment(s) and send back the observed count summed across all directions. True means you get one set of data for each direction of the road segment.BOOLEANtrue or falseY
roadTypesAn array of strings representing the different road types for which you want data. An empty array means all road types.ARRAYSee OSM road types in the Data Dictionary.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
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.

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 e.g. if you didn’t provide credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs.

Response Schema

AttributeDescriptionData TypeDefined Value Set
CardinalDirectionThe direction of the road segment in terms of “N”, “NE”, “E”, etcSTRING“N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW”
DirectionThe direction of travel of the road segment, either 1 or -1INTEGER-
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
NoSegmentMonthsAn array of all months (represented as the first day of the month) for which the segment did not exist and there are no segment predecessors.ARRAY-
ObservedCount

The total observed count for this road segment.

Note:

In the event that a road segment did not exist across the entire date range analyzed (due to historical changes to the basemap), but Geotab has established a reasonable predecessor for a missing month, the road segment predecessor will be utilized as applicable. In the instance where there are multiple predecessors identified (for example, in the instance of a merge of road segments), the road segment with the maximum observed count for a month will be used to calculate observed counts.

INTEGER-
ObservedCountByFuelType

Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: FuelType (string) - fuel type name. ObservedCount (integer) - number of traversals. VehicleCount (integer) - number of vehicles.

ARRAY-
ObservedCountByIndustry

Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: NAICS_Code_1 (integer) - NAICS code 1. ObservedCount (integer) - number of traversals. VehicleCount (integer) - number of vehicles.

ARRAY-
ObservedCountByVehicleClass

Array of objects representing the observed count of traversals and vehicles of 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. ObservedCount (integer) - number of traversals. VehicleCount (integer) - number of vehicles.

ARRAY-
ObservedCountByVocation

Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: VocationId (integer) - unique identifier for the vocation. Vocation (string) - vocation name. ObservedCount (integer) - number of traversals. VehicleCount (integer) - number of vehicles.

ARRAY-
RoadTypeThe road type of road segment.STRINGList of OSM road types. Any value from the “Backend Value” column found here.
SegmentIdThe ID of the road segment for which observed counts are being reported.STRING-
UsedSegmentHistoryIndicates whether segment predecessors have been utilized (true) or not (false).BOOLtrue or false
VehicleCountThe aggregate number of vehicles observed for the road segment, given the applied filters.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“State”, ”County”, ”City”, ”CTR”, ”ZIP”, “TAZ”, “FSA”, “Segment”, or “Custom”

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 API Request Example for more details.

AttributeDescriptionData TypeDefined Value Set
AggregationUnitThe time based unit by which to aggregate data.STRING
  • “Hour”

  • “HourOfDay”

  • “DayOfWeek”

  • “Day”

  • “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

  • hourofday - <YYYY-MM-DDTHH:00:00>, e.g 2024-09-24T16:00:00

  • dayofweek - numeric value for day of week where Sunday is 1 and Saturday is 7

  • day - <YYYY-MM-DD>, e.g. 2024-09-24

month - number of the month, e.g. 1 or 12
STRING-
CardinalDirectionThe direction of the road segment in terms of “N”, “NE”, “E”, etcSTRING[“N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW”]
DirectionThe direction of travel of the road segment, either 1 or -1INTEGER
ISO_3166_2The ISO 3166:2 code of the zone.STRING-
ObservedCountThe total observed count for this road segment.
Note:

In the event that a road segment did not exist across the entire date range analyzed (due to historical changes to the basemap), but Geotab has established a reasonable predecessor for a missing month, the road segment predecessor will be utilized as applicable. In the instance where there are multiple predecessors identified (for example, in the instance of a merge of road segments), the road segment with the maximum observed count for a month will be used to calculate observed counts.

INTEGER-
ObservedCountByFuelType

Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains:

  • FuelType (string) - fuel type name.

  • ObservedCount (integer) - number of traversals.

  • VehicleCount (integer) - number of vehicles.

ARRAY-
ObservedCountByVehicleClass

Array of objects representing the observed count of traversals and vehicles of 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.

  • ObservedCount (integer) - number of traversals.

  • VehicleCount (integer) - number of vehicles.

ARRAY-
ObservedCountByVocation

Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains:

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

  • Vocation (string) - vocation name.

  • ObservedCount (integer) - number of traversals.

  • VehicleCount (integer) - number of vehicles.

ARRAY-
RoadTypeThe road type of road segment.STRINGList of OSM road types. Any value from the “Backend Value” column found here.
SegmentIdThe ID of the road segment for which observed counts are being reported.STRING-
UsedSegmentHistoryIndicates whether segment predecessors have been utilized (true) or not (false).BOOLEANtrue or false
VehicleCountThe aggregate number of vehicles observed for the road segment, given the applied filters.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

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

Sample parameters

Sample parameters that should go inside your functionParameters object.

{
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"}, 
"isDirectional":false,
"queryType":"getObservedCounts",
"roadTypes":['motorway'],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"zones":[{
    "ZoneId":"32003", 
    "ISO_3166_2":"US-NV", 
    "ZoneType":"County"
}]
}

Sample parameters that should go inside your functionParameters object for time series aggregation.

{
"aggregationUnits":["day"],
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"}, 
"generateTimeSeries":false,
"isDirectional":false,
"queryType":"getObservedCounts",
"roadTypes":['motorway'],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"zones":[{
    "ZoneId":"32003", 
    "ISO_3166_2":"US-NV", 
    "ZoneType":"County"
}]
}