Event Objects

These event notifications are delivered over WebSockets or MQTT. MQTT is a fast becoming a valid Pub-Sub alternative to WebSockets.

Trip Finished

Description

A trip has been completed.

Scopes

Requiresscope:trip scope. For access to all fields,scope:location andscope:vehicle are also needed.

Trigger

Sent after a trip is completed and processed. In a case of trips being uploaded after a time delay, we may fire events for multiple trips at once. Thus, one should not consider receipt of thetrip:finished webhook as an indicator that the trip has just recently completed, although that will be the case most of the time. Instead, if the use of this data is based on the time the event happened, the timestamps in the trip objectsstarted_at andended_at fields should be consulted.

Timeout limit

This event will fire when it is received by the server. There is no timeout.

Example Trip Finished Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "trip:finished",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "trip" {
    // Trip Object (matches REST API)
  }
}

Ignition On

Description

A vehicle has been turned on.

Scopes

Requiresscope:vehicle:events scope. For access to all fields,scope:location,scope:vehicle andscope:behavior are also required.

Trigger

Sent when vehicle ignition is turned on.

This event is sent in real-time and requires a working internet connection to be present and connected.

This event is useful for triggering automated services that need to respond in realtime to being in the car. If the client (the smartphone app) is not connected to the VehicleMind adapter at the time of ignition but connects shortly thereafter, theignition:on event will be sent when connection is established. The client, in turn, will attempt to send the event to our servers, retrying up to five times at short intervals, after which it will give up. In practice, if there is not a working connection present in this trip, event will never be sent via webhook or websocket.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Example Ignition On Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "ignition:on",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

Ignition Off

Description

A vehicle has been turned off.

Scopes

Requires scope:vehicle:events scope. For access to all fields scope:location and scope:vehicle are also needed.

Trigger

Sent when vehicle ignition is turned off. This event is useful for triggering automated services that need to respond in realtime to parking or finishing a trip.

The same delivery rules asignition:on apply. Additionally, some cars do not indicate to us explicitly when the ignition is turned off and in those cases we infer from other signals, which may add a time delay of one minute for confirmation of the inference.

Whether inferred or not,ignition:off will come sooner thantrip:finished will — generally the gap between the two is under 30 seconds, but in some cases can be longer.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Example Ingnition Off Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "ignition:off",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}

Speeding

Description

A speed threshold has been crossed.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent after a "velocity exceeded threshold" event occurs.

These events will be generated for exceeding each of 110, 120, and 128 km/h (km per hour). They will be generated once per threshold crossing. To trigger the same threshold event, a user must dip 5 km/h below the threshold first. This is to avoid rapid re-crossings — e.g. hovering right between 108 and 110 km/h.

The same delivery rules as ignition:on apply.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Example Speeding Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:speeding",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "velocity_kph": 112.654
}

Hard Brake Notification

Description

A hard brake event occurred.

Scopes

Requires scope:vehicle:events scope. For access to all fields scope:location and scope:vehicle are also needed.

Trigger

Sent when a hard braking event occurs.

Some events will be filtered out in post-trip processing. Hard brakes are determined in real-time with a basic algorithm that generates the webhook/websocket events. The simple rule is a speed decrease of more than 11 km/h per second.

Once a trip is completed, these events are run through a more advanced algorithm. In that second pass, some of the events are deemed false-positives, or circumstantially explainable. In these instance, they will not be recorded into the ultimate REST objects, though the webhook/websocket events will have already fired.

Subsequent hard brakes within five seconds of the original will be disregarded.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket event will not be generated.

Example Hardbrake Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:hard_brake",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

Hard Acceleration

Description

A hard acceleration has occurred.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when a hard acceleration event occurs.

Some events will be filtered out in post-trip processing. Similar to hard brake events, some hard accel events which fired as webhooks/websockets will be filtered out in post trip processing. Also, the simple definition is 11 km/h per second acceleration.

Subsequent hard accels within five seconds of the original will be disregarded.

Timeout limit

This event has a timeout of five minutes from creation. If it is received by our server after that time, a webhook or websocket will not be generated.

Example Hard Acceleration Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "notification:hard_accel",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "g_force": 0.3
}

MIL On

Description

The MIL (check engine light) is on.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when an MIL (check engine light) comes on. MIL stands for malfunction indicator light, also known as the check engine light. This event will return an array of DTCs, or Diagnostic Trouble Codes.

Often, when a check engine light comes on, there are more than one DTCs contributing to the event. dtcs is an array and can include more than one trouble code. Also, more than onemil:on events may be fired before anmil:off event if additional DTC codes come on after the initialmil:on event.

Timeout limit

This event will fire when it is received by our server. There is no timeout.

Example MIL On Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "mil:on",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "created_at": "2015-04-12T17:44:11.123Z"
    }
  ]
}

MIL Off

Description

The MIL (check engine light) is off.

Scopes

Requires scope:vehicle:events scope. For access to all fields, scope:location and scope:vehicle are also needed.

Trigger

Sent when an MIL (check engine light) goes off. Note that dtcs is an array and can include more than one trouble code, if more than one contributed to the MIL event.

Timeout limit

This event will fire when it is received by our server. There is no timeout.

Example MIL Off Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "mil:off",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location": {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  },
  "dtcs": [
    {
      "code": "P0442",
      "description": "Small fuel vapor leak in EVAP system",
      "created_at": "2015-04-12T17:44:11.123Z"
    }
  ],
  "user_cleared": true
}

Location Updated

Description

A ping of vehicle location

Scopes

Requires scope:current_location scope. For access to all fields scope:vehicle is also needed.

Trigger

Sent every minute during a drive (if GPS available).

Example Location Updated Event Notification

{
  "id": "f61ba3d5-a68e-43eb-a731-0db871b4d3a3",
  "user": {
    "id": "U_ffd955ba63db5c25",
    "url": "https://api.VehicleMind.com/user/U_ffd955ba63db5c25/"
  },
  "type": "location:updated",
  "created_at": "2015-04-12T17:45:18.123Z",
  "time_zone": "America/Los_Angeles",
  "location" : {
    "lat": 37.757076,
    "lon": -122.448120,
    "accuracy_m": 10,
    "created_at": "2015-04-12T17:45:01.123Z"
  },
  "vehicle": {
    "id": "C_507d6f1bd6d9b855",
    "url": "https://api.VehicleMind.com/vehicle/C_507d6f1bd6d9b855/"
  },
  "device" : {
    "id": "021ac91c826b12eca99e685c"
  }
}