queryType: getSpeedAnalysisPerSegment*

The getSpeedAnalysisPerSegment queryType is passed to the API to get speed related metrics on a per road segment basis.

Note:

See Special Case APIs for more information.

Note:

This API is subject to tighter rate limit restrictions.

You must pass a value for roadTypes to this API in order to retrieve data.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getSpeedAnalysisPerSegment.STRINGgetSpeedAnalysisPerSegmentY
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
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 segment.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-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

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”]
DirectionIndicates the direction of traffic flow in relation to the definition of the segment geography. For directional analysis: 1 indicates the traffic flow is in the direction of the segment; -1 indicates the traffic flow is in the opposite direction of the segment definition. For non-directional analysis: value is always 0.INTEGER[0,1,-1]
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 road 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-
RoadTypeOSM road type.STRINGSee OSM Road Mapping.
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-
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 road segment (mph or km/h).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"},
"excludeServiceRoads":true,
"isDirectional":true,
"isMetric":false,
"queryType":"getSpeedAnalysisPerSegment",
"roadTypes":['motorway'],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"vehicleClassSchemeId": 2,
"vehicleClasses":[],
"zones":[{
    "ZoneId":"32003",
    "ISO_3166_2":"US-NV",
    "ZoneType":"County"
	}]

}