queryType: getHarshEventsPerSegment*

The getHarshEventsPerSegment queryType is passed to the API to get the harsh event characteristics by road segments for a selected region.

Note:

See Special Case APIs for more information.

Harsh event metrics such as harsh braking, cornering, and acceleration are used to assess area-based safety risk.

Parameters

ParameterDescriptionTypeDefined Value SetValue Req'd
queryTypeMust equal getHarshEventsPerSegment.STRINGgetHarshEventsPerSegmentY
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".

Note:

A minimum date range of 5 days is required. Analysis must have 5 days between dateRange and daysOfWeek.

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
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
roadTypesArray of strings representing the different road types for which you want data. Pass an empty array to return results for all road types, or pass one or more types to filter.ARRAYList of OSM road types. See the Road Types table. Pass the values from the 2nd column.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 – A custom zone ID, a segment ID, or a standard zone ID such as county ID, city ID, etc.

  • ISO_3166_2 – The ISO code of the standard zone. Does not apply to custom zones, segments or related roads and can be set to null.

  • ZoneType – the type of zone.

ARRAY

  • ZoneType - “Custom”

  • “Segment”

  • “State”

  • “County”

  • “City”

  • “TAZ”

  • “ZIP”

  • “CTR”

  • “FSA”

Y
magnitudeBins

Array of float representing the upper bounds (inclusive) of harsh event magnitude bins (m/s2) on which to report aggregation metrics.

The lower bound for a bin is the previous magnitude in the array (non-inclusive).

The lowest lower bound will start at 0, and go to the first value into the array. The final bin will be the highest value in the array to +inf.

For example, the array [2.32, 3.54, 5.43] would create the following bins: (0, 2.32], (2.32, 3.54], (3.54, 5.43], (5.43, +inf)

ARRAY-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
AccelerationEventsPerTenThousandTripsThe count of acceleration harsh events along a road segment per 10,000 vehicle traversals.FLOAT-
BrakingEventsPerTenThousandTripsThe count of braking harsh events along a road segment per 10,000 vehicle traversals.FLOAT-
CardinalDirectionThe direction of the road segment.STRING[“N”, “NE”, “E”, “SE”, “S”, “SW”, “W”, “NW”]
CorneringEventsPerTenThousandTripsThe count of cornering harsh events along a road segment per 10,000 vehicle traversals.FLOAT-
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.INT[0,1,-1]
HarshEventsByHour

Array of objects representing the observed count of harsh events by hour. Each object contains:

  • Hour (integer) - The hour of data being recorded for (0 - 23)

  • ObservedHarshEvents (integer) - number of harsh events.

  • ObservedAccelerationEvents (integer) - number of acceleration events.

  • ObservedBrakingEvents (integer) - number of braking events.

  • ObservedCorneringEvents (integer) - number of cornering events.

  • ObservedCount (integer) - number of vehicle traversals.

ARRAY-
HarshEventsByIndustry

Array of objects representing the observed count of harsh events by industry. Each object contains:

  • NAICS_Code_1 (integer) - unique identifier for the Industry.

  • ObservedHarshEvents (integer) - number of harsh events.

  • ObservedAccelerationEvents (integer) - number of acceleration events.

  • ObservedBrakingEvents (integer) - number of braking events.

  • ObservedCorneringEvents (integer) - number of cornering events.

  • ObservedCount (integer) - number of vehicle traversals.

ARRAY-
HarshEventsByVehicleClass

Array of objects representing the observed count of harsh events by 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.

  • ObservedHarshEvents (integer) - number of harsh events.

  • ObservedAccelerationEvents (integer) - number of acceleration events.

  • ObservedBrakingEvents (integer) - number of braking events.

  • ObservedCorneringEvents (integer) - number of cornering events.

  • ObservedCount (integer) - number of vehicle traversals.

ARRAY-
HarshEventsByVocation

Array of objects representing the observed count of harsh events by vocation. Each object contains:

  • VocationId (integer) - unique identifier for the vocation.

  • Vocation (string) - vocation name.

  • ObservedHarshEvents (integer) - number of harsh events.

  • ObservedAccelerationEvents (integer) - number of acceleration events.

  • ObservedBrakingEvents (integer) - number of braking events.

  • ObservedCorneringEvents (integer) - number of cornering events.

  • ObservedCount (integer) - number of vehicle traversals.

ARRAY-
HarshEventsByMagnitude

Array of objects representing the observed count of harsh events by magnitude bins. Each object contains:

  • Magnitude (string) — a string representation of the magnitude bin.

  • LowerBound (float) — the lower bound magnitude (non-inclusive) (m/s2).

  • UpperBound (float) — the upper bound magnitude (inclusive) (m/s2).

  • ObservedHarshEvents (integer) - number of harsh events.

  • ObservedAccelerationEvents (integer) - number of acceleration events.

  • ObservedBrakingEvents (integer) - number of braking events.

  • ObservedCorneringEvents (integer) - number of cornering events.

ARRAY-
HarshEventsPerTenThousandTripsThe count of total harsh events along a road segment per 10,000 vehicle traversals.FLOAT-
ObservedCountThe aggregate number of observed vehicle traversals for the road segment, given the applied filters.INTEGER-
ObservedHarshEventsThe count of total harsh events along a road segment for the given time.INTEGER-
ObservedAccelerationEventsThe count of acceleration based harsh events along a road segment for the given time.INTEGER-
ObservedBrakingEventsThe count of braking based harsh events along a road segment for the given time.INTEGER-
ObservedCorneringEventsThe count of cornering based harsh events along a road segment for the given time.INTEGER-
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-

Sample parameters

{
"queryType":"getHarshEventsPerSegment",
"dateRange":{"DateFrom":"2025-10-01", "DateTo":"2025-10-07"},
"isMetric":False,
"isDirectional":False,
"zones":[{
	"ZoneId":"1938595",
	"ISO_3166_2":"US-IA",
	"ZoneType":"City" }]
}