queryType: getHarshEventsPerSegment*
The getHarshEventsPerSegment queryType is passed to the API to get the harsh event characteristics by road segments for a selected region.
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
| Parameter | Description | Type | Defined Value Set | Value Req'd |
|---|---|---|---|---|
| queryType | Must equal getHarshEventsPerSegment. | STRING | getHarshEventsPerSegment | Y |
| dateRange |
An object defining the analysis date range. Each object contains:
Note:
A minimum date range of 5 days is required. Analysis must have 5 days between dateRange and daysOfWeek. | OBJECT | - | Y |
| daysOfWeek | Array of integers representing each week day. Can send an empty array to return all days. | ARRAY | [1,7] (1 = Sunday, 2 = Monday, etc.) | N |
| isDirectional | True if you want one record per direction, false if you just want an overall average of both directions. | BOOLEAN | True or false | Y |
| isMetric | True for data to be returned in metric units, false for imperial. | BOOLEAN | true or false | Y |
| roadTypes | Array of strings representing the different road types for which you want data. Must pass at least one type. Pass an empty array for all. | ARRAY | List of OSM road types. See the Road Types table (excludes Local Roads and Other. Pass the values from the 2nd column) | Y |
| vehicleClassSchemeId | Determines 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 | 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
| ARRAY |
| 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
| Code | Type | Description |
|---|---|---|
| 200 | JSON | The requested data. |
| 401 | JSON | Occurs for various unauthorized tasks, such as not providing credentials in your parameters. |
| 500 | JSON | Occurs if an internal server error occurs. Contact altitudesupport@geotab.com if this occurs. |
Response Schema
| Attribute | Description | Data Type | Defined Value Set |
|---|---|---|---|
| AccelerationEventsPerTenThousandTrips | The count of acceleration harsh events along a road segment per 10,000 vehicle traversals. | FLOAT | - |
| BrakingEventsPerTenThousandTrips | The count of braking harsh events along a road segment per 10,000 vehicle traversals. | FLOAT | - |
| CardinalDirection | The direction of the road segment. | STRING | “[N”, “NE”, “E”, SE”, “S”, “SW”, “W”, “NW”] |
| CorneringEventsPerTenThousandTrips | The count of cornering harsh events along a road segment per 10,000 vehicle traversals. | FLOAT | - |
| Direction | Indicates 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:
| ARRAY | - |
| HarshEventsByIndustry |
Array of objects representing the observed count of harsh events by vocation. Each object contains:
| ARRAY | - |
| HarshEventsByVehicleClass |
Array of objects representing the observed count of harsh events by vehicle class. Each object contains:
| ARRAY | - |
| HarshEventsByVocation |
Array of objects representing the observed count of harsh events by vocation. Each object contains:
| ARRAY | - |
| HarshEventsByMagnitude |
Array of objects representing the observed count of harsh events by magnitude bins. Each object contains:
| ARRAY | - |
| HarshEventsPerTenThousandTrips | The count of total harsh events along a road segment per 10,000 vehicle traversals. | FLOAT | - |
| ObservedCount | The aggregate number of observed vehicle traversals for the road segment, given the applied filters. | INTEGER | - |
| ObservedHarshEvents | The count of total harsh events along a road segment for the given time. | INTEGER | - |
| ObservedAccelerationEvents | The count of acceleration based harsh events along a road segment for the given time. | INTEGER | - |
| ObservedBrakingEvents | The count of braking based harsh events along a road segment for the given time. | INTEGER | - |
| ObservedCorneringEvents | The count of cornering based harsh events along a road segment for the given time. | INTEGER | - |
| RoadType | OSM road type. | STRING | See OSM Road Mapping. |
| SegmentId | The ID of the road segment. | STRING | - |
| SegmentLength | The length of the segment in metric units (kilometers) or imperial units (miles) based on the value of isMetric. | FLOAT | - |
Sample parameters
{
"dateRange":{"DateFrom":"2023-10-01", "DateTo":"2023-10-07"},
"isMetric":false,
"queryType":"getHarshEventsPerSegment",
"zones":[{
"ZoneId":"32003",
"ISO_3166_2":"US-NV",
"ZoneType":"County"
}]
}