queryType: getRoadReverseLookup*

The getRoadReverseLookup queryType is passed to the API to filter road segments based on various criteria.

Note:

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

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getRoadReverseLookup.STRINGgetRoadReverseLookupY
aggregationPeriod

An object defining the aggregation requirements for the analysis. Each object contains:

  • Value (integer) - the time interval and can be any integer.

  • Unit (string) - unit for the interval and can be any of “minute”, “hour” or “week”.

  • For example, if you want the breakdown of road segments by hour that matches your criteria, you would enter 1 for Value and “hour” for Unit. If you just want a summary of the entire time period, pass any number for Value and “*” for Unit.

OBJECTUnit - “minute”, “hour”, “week” or “*”Y
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
filterAndConditionWhether the returned data has to pass all filters (true/And), or any filter (false/Or).BOOLEANtrue: And,false: OrY
isDirectionalTrue if you want one record per direction, false if you just want an overall average of both directions.BOOLEANtrue or falseY
isMetricTrue for data to be returned in metric units, false for imperial.BOOLEANtrue or falseY
percentilesArray of integers representing what percentiles you want the metrics broken up into. Default if not provided is [15,50,85].ARRAY[1-99]N
roadTypesArray of strings representing the different road types for which you want data. Must pass at least one type.ARRAYList of OSM road types. See the Road Types table.Y
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.

ARRAY
  • ZoneType - “Custom”

  • “Segment”

  • “State”

  • “County”

  • “City”

  • “TAZ”

  • “ZIP”

  • “CTR”

  • “FSA”

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 FilterValue and FilterMode. If you want all segments that have a speed limit greater than 60mph, for example, you would pass “speedLimit”:{“FilterValue”: 60, “FilterMode”: “greater”}.

OBJECT

FilterValue - any valid float number.

FilterMode - “greater”, “less”.

N
spotSpeedFilter

Same as speedLimit above, but refers to spot speed. Also has an added FilterType property that allows you to specify “average” or “median” for your comparison. For example, you would pass "spotSpeed": {"FilterType": "average", "FilterValue": 0,"FilterMode":"greater"}.

OBJECT

FilterValue - any valid float number.

FilterMode - “greater”, “less”.

FilterType - “average”, “Median”.

N
spotSpeedPctOfSpeedLimitFilterSame as speedLimit above, but refers to the spot speed percentage of the speed limit.OBJECTSee aboveN
spotSpeedPctOfFreeFlowFilterSame as speedLimit above, but refers to the spot speed percentage of free flow.OBJECTSee aboveN
spotSpeedPctOverSpeedLimitFilterSame as speedLimit above, but refers to the percentage of vehicles with spot speed over the speed limit.OBJECTSee aboveN
travelSpeedFilterSame as spotSpeed above, but refers to the travel speed of vehicles.OBJECTSee aboveN
travelSpeedPctOfSpeedLimitFilterSame as speedLimit above, but refers to the travel speed percentage of the speed limit.OBJECTSee aboveN
travelSpeedPctOfFreeFlowFilterSame as speedLimit above, but refers to the travel speed percentage of free flow.OBJECTSee aboveN
travelSpeedPctOverSpeedLimitFilterSame as speedLimit above, but refers to the percentage of vehicles with travel speed over the speed limit.OBJECTSee aboveN

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
AggregationPeriodFromThe time at the start of the aggregation period. For a summary analysis, the value will be “Summary”.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 -1FLOAT-
DominantPace

An object representing the 10 mph or 10km/h range with the highest share of traffic. The object contains:

  • PaceFrom (float) - lower bound of bucket.

  • PaceTo (float) - upper bound of bucket.

OBJECT-
FreeFlowSpeedThe free flow speed for the given set of filters across the segment (mph or km/h).FLOAT-
ObservedCountThe 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:

  • 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 vocation. 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-
SampleSizePctByPace

Array of objects representing the size percentage for each pace band. Each object contains:

  • PaceFrom (float) - the lower bound of the pace band.

  • PaceTo (float) - the upper bound of the pace band.

  • SampleSizePct (float) - percentage of the samples that fall into this pace band.

ARRAY-
RoadTypeOSM road type.STRINGSee OSM Road Mapping.
SegmentIdThe ID of the road segment.STRING-
SegmentLengthThe length of the segment in metric units (kilometers) or imperial units (miles) based on the value of isMetric.FLOAT-
SpeedLimitThe speed limit of the segment (mph or km/h).INTEGER-
SpotSpeedAvgThe average Spot Speed.FLOAT-
SpotSpeedHarmonicHarmonic mean of the maximum individual speed observed as a vehicle drives through the selected roads. Measured in km/h or mph. (Spot Speed)FLOAT-
SpotSpeedPctOfFreeFlowSpot Speed as a percentage of Free-flow speed.FLOAT-
SpotSpeedPctOfSpeedLimitThe average Spot Speed as a percentage of the weighted average speed limit.FLOAT-
SpotSpeedPctOverSpeedLimitThe 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:

  • 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, 50th and 85th percentiles are provided by default.

ARRAY-
SpotSpeedStdevStandard deviation of Spot Speed.FLOAT-
TravelSpeedAvgThe average Travel Speed (mph or km/h).FLOAT-
TravelSpeedHarmonicHarmonic 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-
TravelSpeedPctOfFreeFlowTravel Time speed as a percentage of Free-flow speed.FLOAT-
TravelSpeedPctOfSpeedLimitThe average Travel Time speed as a percentage of the weighted average speed limit.FLOAT-
TravelSpeedPctOverSpeedLimitThe 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:

  • Percentile (integer): the percentile value.

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

Note:

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

ARRAY-
TravelSpeedStdevStandard deviation of Travel Speed.FLOAT-
TravelTimeAvgAverage Travel Time (seconds).FLOAT-
TravelTimeFreeFlowFree-flow Travel Time (seconds).FLOAT-
TravelTimeHarmonicHarmonic mean of the time taken to travel along the selected roads (Travel Time in seconds).FLOAT-
TravelTimeDelayFromFreeFlow50th 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:

  • Percentile (integer): the percentile value.

  • Value (float): the calculated percentile travel time value (seconds).

Note:

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

ARRAY-
TravelTimeReliabilityRatio of the 85th percentile Travel Time to the median (50th percentile) Travel Time.FLOAT-
VehicleCountThe 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"
	}]

}