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.
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
| Parameter | Description | Type | Defined Value Set | Value Req'd |
|---|---|---|---|---|
| queryType | Must equal getObservedCounts. | STRING | getObservedCounts | 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
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 |
| 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 |
| isDirectional | False 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. | BOOLEAN | true or false | Y |
| roadTypes | An array of strings representing the different road types for which you want data. An empty array means all road types. | ARRAY | See OSM road types in the Data Dictionary. | N |
| timeRange |
An object representing the analysis time range. Each object contains:
The default is “00:00:00” to “23:59:59.999”. | 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 |
| 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 e.g. if you didn’t provide 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 |
|---|---|---|---|
| CardinalDirection | The direction of the road segment in terms of “N”, “NE”, “E”, etc | STRING | “N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW” |
| Direction | The direction of travel of the road segment, either 1 or -1 | INTEGER | - |
| ISO_3166_2 | The ISO 3166:2 code of the zone. | STRING | - |
| NoSegmentMonths | An 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: | ARRAY | - |
| ObservedCountByIndustry |
Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: | ARRAY | - |
| ObservedCountByVehicleClass |
Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: | ARRAY | - |
| ObservedCountByVocation |
Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains: | ARRAY | - |
| RoadType | The road type of road segment. | STRING | List of OSM road types. Any value from the “Backend Value” column found here. |
| SegmentId | The ID of the road segment for which observed counts are being reported. | STRING | - |
| UsedSegmentHistory | Indicates whether segment predecessors have been utilized (true) or not (false). | BOOL | true or false |
| VehicleCount | The 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 | - |
| ZoneId | The zone id for which the data is returned. | STRING | - |
| ZoneType | The 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.
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| AggregationUnit | The time based unit by which to aggregate data. | STRING |
|
| AggregationValue | The associated AggregationUnit value. The value set is based on the AggregationUnit value. Value format based on AggregationUnit:
| STRING | - |
| CardinalDirection | The direction of the road segment in terms of “N”, “NE”, “E”, etc | STRING | [“N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW”] |
| Direction | The direction of travel of the road segment, either 1 or -1 | INTEGER | |
| ISO_3166_2 | The ISO 3166:2 code of the zone. | STRING | - |
| 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:
| ARRAY | - |
| ObservedCountByVehicleClass |
Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains:
| ARRAY | - |
| ObservedCountByVocation |
Array of objects representing the observed count of traversals and vehicles of each vehicle class. Each object contains:
| ARRAY | - |
| RoadType | The road type of road segment. | STRING | List of OSM road types. Any value from the “Backend Value” column found here. |
| SegmentId | The ID of the road segment for which observed counts are being reported. | STRING | - |
| UsedSegmentHistory | Indicates whether segment predecessors have been utilized (true) or not (false). | BOOLEAN | true or false |
| VehicleCount | The 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:
| STRING | - |
| ZoneId | The zone id for which the data is returned. | STRING | - |
| ZoneType | The 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"
}]
}