queryType: getSpeedAnalysisSummary

The getSpeedAnalysisSummaryqueryType is passed to the API to retrieve the data needed for the speed summary tab.

This query provides the information required to generate the first two charts on the trend analysis tab of the speed analysis screen.

Parameters

These parameters should be passed to the functionParameters object regardless of which method you choose to make an API request.

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getSpeedAnalysisSummary.STRINGgetSpeedAnalysisSummaryY
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
isDirectionalFalse means we ignore the direction of the road segment(s) and send back the average of all directions. True means you get one set of data for each direction of the road segmentBOOLEANtrue 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
segmentsDirectional

Array of objects representing directional road segments. Each object contains:

  • SegmentId (string) - road segment ID.

  • Direction (integer) - the direction of travel in relation to the segment definition. 1 indicates in the direction of the segment definition; -1 indicates the opposite direction to the segment definition.

For example: [{SegmentId: "5107220114254191964", Direction: 1}]. You must pass either segmentsDirectional or zones.

ARRAYDirection: 1,-1N
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.

You must pass either segmentsDirectional or zones.

ARRAY

ZoneType - “Custom”, or “Segment”

N

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”, etc. This attribute is only populated when IsDirectional is true. For custom zones this represents the cardinal direction with the most relative road coverage.STRING“N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW”
CorridorDirectionFor analysis involving a corridor where IsDirectional is set to TRUE: “1” refers to traffic that traversed the corridor in the order of segments provided. “-1” refers to traffic in the inverse order.INTEGER[1, -1]
CorridorLengthThe total length of the selected road segments. This attribute is only populated for corridor analysis (segment inputs only).FLOAT-
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-
FreeFlowSpeedAvgThe average free flow speed for the given set of filters across the road segments (mph or km/h).FLOAT-
ObservedCountThe aggregate number of observed vehicle passes for the road segment, given the applied filters. Observed count value is only returned for a single segment query.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-
SegmentsDirectional

Array of objects representing directional segments in the order of the corridor as input. Each object contains:

  • SegmentId (string) - road segment ID.

  • Direction (integer) - the direction of travel in relation to the segment definition. 1 indicates in the direction of the segment definition; -1 indicates the opposite direction to the segment definition.

This attribute is populated if a corridor of segments was provided to the API.

ARRAY-
SpeedLimitAvgThe average speed limit, weighted by traffic volume across all roads selected (km/h or mph).INTEGER-
SpeedLimitMaxThe highest speed limit across selected roads (km/h or mph).INTEGER-
SpeedLimitMinThe lowest speed limit across selected roads (km/h or mph).INTEGER-
SpotSpeedAvgThe average Spot Speed (mph or km/h).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-
TravelTimeDelayFromFreeFlow50th percentile Travel Time minus Free-flow 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-
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"},
"isDirectional":true,
"isMetric":false,
"queryType":"getSpeedAnalysisSummary",
"segmentsDirectional":[
 	 {"SegmentId":"-5413282495872703901", "Direction":1},
      {"SegmentId":"-4350021053557322330", "Direction":1},
      {"SegmentId":"-5326185399566610743", "Direction":1}
	],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"vehicleClassSchemeId": 2,
"vehicleClasses":[]
}