queryType: getRoadReverseLookup*
The getRoadReverseLookup queryType is passed to the API to filter road segments based on various criteria.
See Special Case APIs for more information.
This API can be used to quickly find road segments that have greater than 45 mph average spot speed for the vehicles that travel on them. You must pass a value for roadTypes to this API in order to retrieve data.
Parameters
| Parameter | Description | Type | Defined Value Set | Value Req'd |
|---|---|---|---|---|
| queryType | Must equal getRoadReverseLookup. | STRING | getRoadReverseLookup | Y |
| aggregationPeriod |
An object defining the aggregation requirements for the analysis. Each object contains:
| OBJECT | Unit - “minute”, “hour”, “week” or “*” | Y |
| 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 |
| filterAndCondition | Whether the returned data has to pass all filters (true/And), or any filter (false/Or). | BOOLEAN | true: And,false: Or | Y |
| isDirectional | True if you want one record per direction, false if you just want an overall average of both directions. | BOOLEAN | true or false | Y |
| isMetric | True for data to be returned in metric units, false for imperial. | BOOLEAN | true or false | Y |
| percentiles | Array of integers representing what percentiles you want the metrics broken up into. Default if not provided is [15,50,85]. | ARRAY | [1-99] | N |
| roadTypes | Array of strings representing the different road types for which you want data. Must pass at least one type. | ARRAY | List of OSM road types. See the Road Types table. | Y |
| 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
| ARRAY |
| Y |
| Filters (at least one filter must be provided) |
At least one filter must be provided from the filter parameters listed below. | |||
| speedLimitFilter |
An object containing | OBJECT |
FilterValue - any valid float number. FilterMode - “greater”, “less”. | N |
| spotSpeedFilter |
Same as speedLimit above, but refers to spot speed. Also has an added | OBJECT |
FilterValue - any valid float number. FilterMode - “greater”, “less”. FilterType - “average”, “Median”. | N |
| spotSpeedPctOfSpeedLimitFilter | Same as speedLimit above, but refers to the spot speed percentage of the speed limit. | OBJECT | See above | N |
| spotSpeedPctOfFreeFlowFilter | Same as speedLimit above, but refers to the spot speed percentage of free flow. | OBJECT | See above | N |
| spotSpeedPctOverSpeedLimitFilter | Same as speedLimit above, but refers to the percentage of vehicles with spot speed over the speed limit. | OBJECT | See above | N |
| travelSpeedFilter | Same as spotSpeed above, but refers to the travel speed of vehicles. | OBJECT | See above | N |
| travelSpeedPctOfSpeedLimitFilter | Same as speedLimit above, but refers to the travel speed percentage of the speed limit. | OBJECT | See above | N |
| travelSpeedPctOfFreeFlowFilter | Same as speedLimit above, but refers to the travel speed percentage of free flow. | OBJECT | See above | N |
| travelSpeedPctOverSpeedLimitFilter | Same as speedLimit above, but refers to the percentage of vehicles with travel speed over the speed limit. | OBJECT | See above | N |
Responses
| Code | Type | Description |
|---|---|---|
| 200 | JSON | The requested data. |
| 401 | JSON | Occurs for various unauthorized tasks, such as not providing 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 |
|---|---|---|---|
| AggregationPeriodFrom | The time at the start of the aggregation period. For a summary analysis, the value will be “Summary”. | 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 | FLOAT | - |
| DominantPace |
An object representing the 10 mph or 10km/h range with the highest share of traffic. The object contains:
| OBJECT | - |
| FreeFlowSpeed | The free flow speed for the given set of filters across the segment (mph or km/h). | FLOAT | - |
| ObservedCount | The aggregate number of observed vehicle passes for the road segment, given the applied filters. | INTEGER | - |
| ObservedCountByIndustry |
Array of objects representing the observed count of traversals and vehicles of each industry. 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 vocation. Each object contains:
| ARRAY | - |
| SampleSizePctByPace |
Array of objects representing the size percentage for each pace band. Each object contains:
| ARRAY | - |
| RoadType | OSM road type. | STRING | See OSM Road Mapping. |
| SegmentId | The ID of the road segment. | STRING | - |
| SegmentLength | The length of the segment in metric units (kilometers) or imperial units (miles) based on the value of isMetric. | FLOAT | - |
| SpeedLimit | The speed limit of the segment (mph or km/h). | INTEGER | - |
| SpotSpeedAvg | The average Spot Speed. | FLOAT | - |
| SpotSpeedHarmonic | Harmonic mean of the maximum individual speed observed as a vehicle drives through the selected roads. Measured in km/h or mph. (Spot Speed) | FLOAT | - |
| SpotSpeedPctOfFreeFlow | Spot Speed as a percentage of Free-flow speed. | FLOAT | - |
| SpotSpeedPctOfSpeedLimit | The average Spot Speed as a percentage of the weighted average speed limit. | FLOAT | - |
| SpotSpeedPctOverSpeedLimit | The percentage of vehicle passes where the Spot Speed was over the speed limit. | FLOAT | - |
| SpotSpeedPercentiles |
Array of objects representing percentile spot speed values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th, 50th and 85th percentiles are provided by default. | ARRAY | - |
| SpotSpeedStdev | Standard deviation of Spot Speed. | FLOAT | - |
| TravelSpeedAvg | The average Travel Speed (mph or km/h). | FLOAT | - |
| TravelSpeedHarmonic | Harmonic mean of the average speed (km/h or mph) calculated by dividing the total length of the selected roads by the travel time across those roads (Travel Speed). | FLOAT | - |
| TravelSpeedPctOfFreeFlow | Travel Time speed as a percentage of Free-flow speed. | FLOAT | - |
| TravelSpeedPctOfSpeedLimit | The average Travel Time speed as a percentage of the weighted average speed limit. | FLOAT | - |
| TravelSpeedPctOverSpeedLimit | The percentage of vehicle passes where the Travel Time speed was over the speed limit. | FLOAT | - |
| TravelSpeedPercentiles |
Array of objects representing percentile travel speed values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th, 50th and 85th percentiles are provided by default. | ARRAY | - |
| TravelSpeedStdev | Standard deviation of Travel Speed. | FLOAT | - |
| TravelTimeAvg | Average Travel Time (seconds). | FLOAT | - |
| TravelTimeFreeFlow | Free-flow Travel Time (seconds). | FLOAT | - |
| TravelTimeHarmonic | Harmonic mean of the time taken to travel along the selected roads (Travel Time in seconds). | FLOAT | - |
| TravelTimeDelayFromFreeFlow | 50th percentile Travel Time minus Free-flow Travel Time (seconds). | FLOAT | - |
| TravelTimePercentiles |
Array of objects representing percentile travel time values for input percentiles. Each object contains:
Note:
If no percentiles are input, the 15th, 50th and 85th percentiles are provided by default. | ARRAY | - |
| TravelTimeReliability | Ratio of the 85th percentile Travel Time to the median (50th percentile) Travel Time. | FLOAT | - |
| VehicleCount | The aggregate number of vehicles observed for the road segment, given the applied filters. | INTEGER | - |
Sample parameters
{
"aggregationPeriod":{"Value": 1, "Unit":"*"},
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"},
"excludeServiceRoads":true,
"filterAndCondition":false,
"isDirectional":true,
"isMetric":false,
"queryType":"getRoadReverseLookup",
"roadTypes":['motorway'],
"spotSpeedFilter":{"FilterType":"average", "FilterValue":45, "FilterMode":"greater"},
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"vehicleClassSchemeId": 2,
"vehicleClasses":[],
"zones":[{
"ZoneId":"32003",
"ISO_3166_2":"US-NV",
"ZoneType":"County"
}]
}