queryType: getSpeedMapMetrics*

The getSpeedMapMetrics queryType gets static road segment characteristic data about the selected region.

Note:

See Special Case APIs for more information.

This API call pulls data such as segment ID, Geography, speed limit and vehicle speed metrics like travel speed and vehicle count.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getSpeedMapMetrics.STRINGgetSpeedMapMetricsY
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
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

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks e.g. if you didn’t provide credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs.

Response Schema

AttributeDescriptionData TypeDefined Value Set
TravelSpeedAvgThe average speed for all vehicles traversing along the road segment (km/h or mph).FLOAT-
ObservedCountThe aggregate number of observed vehicle passes for the road segment, given the applied filters.INTEGER-
RoadTypeOSM road type.STRINGSee OSM Road Mapping.
SegmentIdThe ID of the road segment. Segments come from breaking down OSM ways into smaller road segments.STRING-
SegmentLengthThe length of the segment in metric units (kilometers) or imperial units (miles) based on the value of isMetric.FLOAT-
SpeedLimitSpeed limit for the road (km/h or mph).INTEGER-
SpotSpeedAvgThe average Spot Speed (mph or km/h).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-
TravelTimeAvgThe average travel time (seconds).FLOAT-
VehicleCountThe aggregate number of vehicles observed for the road segment, given the applied filters.INTEGER-

Sample parameters

{
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"},
"isMetric":false,
"queryType":"getSpeedMapMetrics",
"roadTypes":['motorway'],
"timeRange":{"TimeFrom":"00:00:00", "TimeTo":"23:59:59.999"},
"vehicleClasses":[],
"vehicleClassSchemeId":2,
"zones":[{
    "ZoneId":"32003",
    "ISO_3166_2":"US-NV",
    "ZoneType":"County"
	}]

}