EventType

An EventType represents and event that can be triggered within the Carvoyant system. API users can subscribe to these events using an EventSubscription. This page describes the details of each event type. In the details below you will find the following:

  • Event Scope: Events can be set at the system, account or vehicle scope.
Scope Description Query Path Prefixes
System These subscriptions are created using the Client Credentials mechanism and are not account specific. They allow you to subscribe to system level events. /system
Account These subscriptions are applicable to the account that the access token applies to. /account
Vehicle These subscriptions are applicable to a specific vehicle. They can be specified at the account level in which case the Carvoyant system will ensure that all vehicles on your account have the subscription created for it. /account /vehicle
  • Event Type Key: This is the string that will be used in EventSubscription and EventNotification objects wherever you see {event-type}.
  • Subscription Properties: This will be the list of propertis that are specified when the subscription is created.
  • Supported Notification Periods: This will list which NotificationPeriod values are supported for the event type.

Geo Fence

GeoFence events will trigger when a vehicles location is reported at a certain location. This is evaluated any time a Waypoint is received by the system.

Scope: Vehicle

Event Type Key: GEOFENCE

Subscription Properties

Name Type Description Required for Creation
origin Waypoint The reference location on which to base event notification Required
radius Float The length of the radius extending outward from the origin that creates the GeoFence boundary. This is specified in miles. Required
ignitionStatus String Enumeration: ON OFF RUNNING ANY Defines the required ignition state of the vehicle that must be met in order for the event notification to occur. Required
boundaryCondition String Enumeration: INSIDE OUTSIDE Specifies whether to trigger the event notification if the vehicle is “INSIDE” or “OUTSIDE” of the defined boundary. Required

Supported Notification Periods

  • CONTINUOUS
  • STATECHANGE
  • INITIALSTATE
  • ONETIME

Ignition Status

Ignition status events will trigger when a vehicles engine state (ie, ignition state) is turned on or off.

Scope: Vehicle

Event Type Key: IGNITIONSTATUS

Subscription Properties: No additional properties

Supported Notification Periods

  • STATECHANGE
  • INITIALSTATE
  • ONETIME

Low Battery

The low battery event will trigger when the voltage read from the vehicle falls below 12.0V. For other values, see the Numeric Data Keys event type.

Scope: Vehicle

Event Type Key: LOWBATTERY

Subscription Properties: No additional properties

Supported Notification Periods

  • CONTINUOUS
  • STATECHANGE
  • INITIALSTATE
  • ONETIME

Numeric Data Keys

Numeric data key events will trigger when the value of the specified DataKey meets the criteria. This can be used to customize events off of any numerical data point collected by Carvoyant.

Scope: Vehicle

Event Type Key: NUMERICDATAKEY

Subscription Properties

Name Type Description Required for Creation
dataKey DataKey The DataKey to check against. Note that the following keys are supported: GEN_VOLTAGE, GEN_TRIP_MILEAGE, GEN_ODOMETER, GEN_HEADING, GEN_RPM, GEN_FUELLEVEL, GEN_FUELRATE, GEN_ENGINE_COOLANT_TEMP, GEN_SPEED Required
thresholdValue Float The value that determines when to send the event notification in reference to the corresponding vehicle data. Required
relationship String: ABOVE BELOW EQUALTO Defines the condition that is used to compare the value of the subscription against current vehicle data. Required

Supported Notification Periods

  • CONTINUOUS
  • STATECHANGE
  • INITIALSTATE
  • ONETIME

Time Of Day

The TimeOfDay Subscription allows event notification when a vehicle is operated outside of a defined time period.

Scope: Vehicle

Event Type Key: TIMEOFDAY

Subscription Properties

Name Type Description Required for Creation
startTime String in HH:MM format The time of day that the vehicle is permitted to run. Required
endTime String in HH:MM format The time of day when the vehicle is no longer permitted to run. Required
daysOfWeek Array of String Enumeration: SUN, MON, TUE, WED, THU, FRI, SAT, SUN Represents the days of the week that the vehicle is permitted to run. Required
ignitionStatus String Enumeration: ON OFF RUNNING ANY Defines the required ignition state of the vehicle that must be met in order for the event notification to occur. Required

Supported Notification Periods

  • CONTINUOUS
  • STATECHANGE
  • INITIALSTATE
  • ONETIME

Trouble Code

The trouble code event will trigger when the vehicle reports a Diagnostic Trouble Code (DTC).

Scope: Vehicle

Event Type Key: TROUBLECODE

Subscription Properties: No additional properties

Supported Notification Periods

  • INITIALSTATE
  • ONETIME

Driver Behaviors

Driver behavior events trigger based on how the driver is driving. Each are determined using an internal accelerometer within the device in the vehicle.

Scope: Vehicle

Event Type Keys:
  • VEHICLEHARSHACCEL: Indicates that a high rate of acceleration has been detected.
  • VEHICLEHARSHDECEL: Indicates that a high rate of deceleration has been detected.
  • VEHICLEHARSHRIGHT: Indicates that a hard right turn has been detected.
  • VEHICLEHARSHLEFT: Indicates that a hard left turn has been detected.
  • VEHICLEIMPACT: Indicates that an impact has been detected. Please note that currently, the act of plugging in or unplugging a device to the OBDII port while the vehicle is on may trigger this event.

Note

Driver behavior events will only be triggered while the vehicle is running. Specifically, this means that an impact that takes place while the vehicle is not running will not trigger an alert.

Subscription Properties: No additional properties

Supported Notification Periods

  • INITIALSTATE
  • ONETIME

Vehicle Events

Vehicle events are generally related to events that occur with the vehicle that do not have to do with driving activities.

Scope: Vehicle

Event Type Keys:
  • VEHICLECONNECTED: Indicates that connectivity to the car has been established. For OBDII based cars, this means the device has been plugged in.
  • VEHICLEDISCONNECTED: Indicates that connectivity to the car has been removed. For OBDII based cars, this means the device has been unplugged.
  • VEHICLETOWED: Indicates that the vehicle is being towed. Specifically, this means the vehicle has moved a certain distance (currently 1500 meters) without the vehicle being turned on.

Note

VEHICLETOWED will be triggered if the device is unplugged and then plugged back in after moving the configured distance. If a device is unplugged and then plugged back in that distance away, the vehicle should be started. That will clear the towing indicator on the device.

Subscription Properties: No additional properties

Supported Notification Periods

  • INITIALSTATE
  • ONETIME

Vehicle Creation

These events allow you to react to the creation or deletion of a vehicle on an account.

Scope: Account

Event Type Keys:
  • VEHICLECREATED: Indicates that the vehicle has been created in the system.
  • VEHICLEDELETED: Indicates that the vehicle has been deleted from the system. Note that after receiving a notification that the vehicle has been deleted, you can no longer query against it.

Subscription Properties: No additional properties

Supported Notification Periods

  • ONETIME
  • CONTINUOUS

Account Authorization

This event will notify you of the change in access grants to an account for your client id. At this time, only revoke notifications will be sent.

Scope: System

Event Type Key:

  • AUTHORIZATIONSTATUS: Indicates that the authorization status for the account has changed.

Subscription Properties: No additional properties

Supported Notification Periods

  • ONETIME
  • CONTINUOUS

Notification Properties

Name Type Description
authorizationStatus String Enumeration GRANTED, REVOKED The time of day that the vehicle is permitted to run.