Fun with Driver Report Cards

The sheer volume of data Vinli collects for a given vehicle can be overwhelming at times. That's why it's really important to us to offer a layer of services that nurture, sift, and process that data into something useful for our developers. Behavioral Service is a perfect example of that: we take raw telemetry messages and trip stats, and turn them into a report-card-style output that can be a really handy feature for your app.

Everyone wants to be an A driver, and report cards allow your app to help users work towards or maintain a really good "driving score". This is unlike other Vinli services (like diagnostics, or distance) because a report card is something the user can engage with every day or even every time they drive! This type of high frequency touch point is the kind of thing you need to keep users engaged with your app over time.

Let's dig in to how it works!

The Format

Report Cards live up to their name, with A B C D F results that mimic the marks most of us got in grade school. We even support an I grade which-staying true to the metaphor–stands for Incomplete.

Report Cards Per Trip

At the end of every trip, a report card with one of the letter grades mentioned above is generated. This allows for super snappy feedback to the user... maybe their a little feisty during their morning commute? Perhaps there's a particular route they tend to get lead-footed on? These are the kinds of things that per-trip report cards should help with.

Let's look at an example:

GET https://behavioral.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards

{
  "reportCards": [
    {
      "id": "549d628c-48dc-412d-8087-44a9f82f187e",
      "deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
      "vehicleId": "ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55",
      "tripId": "b9e58eb4-0743-45e9-b9c6-86500f5412bb",
      "grade": "A",
      "links": {
        "self": "https://behavioral.vin.li/api/v1/report_cards/549d628c-48dc-412d-8087-44a9f82f187e",
        "trip": "https://trips.vin.li/api/v1/trips/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55"
      }
    },
    {
      "id": "649d628c-48dc-412d-8087-44a9f82f187e",
      "deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
      "vehicleId": "ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55",
      "tripId": "b9e58eb4-0743-45e9-b9c6-86500f5412bb",
      "grade": "A",
      "links": {
        "self": "https://behavioral.vin.li/api/v1/report_cards/649d628c-48dc-412d-8087-44a9f82f187e",
        "trip": "https://trips.vin.li/api/v1/trips/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55"
      }
    },
    {
      "id": "749d628c-48dc-412d-8087-44a9f82f187e",
      "deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
      "vehicleId": "ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55",
      "tripId": "b9e58eb4-0743-45e9-b9c6-86500f5412bb",
      "grade": "A",
      "links": {
        "self": "https://behavioral.vin.li/api/v1/report_cards/749d628c-48dc-412d-8087-44a9f82f187e",
        "trip": "https://trips.vin.li/api/v1/trips/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55"
      }
    }
  ],
  "meta": {
    "pagination": {
      "remaining": 2,
      "until": "2016-12-13T22:48:25.074Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 3,
      "sortDir": "desc",
      "links": {
        "prior": "https://behavioral.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards?limit=3&until=1460045751460"
      }
    }
  }

Lifetime Report Card

Lifetime Report Cards take into account ALL of the driving that Vinli has observed for a given vehicle or device. The result is an overall driving score or grade. Because of the cumulative nature of this stat, it may take a lot of driving to see changes in behavior reflected in the grade. Don't fret though! This is a good thing, as the grade should be representational of the overall driving behavior score. Here's what it looks like in action:

GET https://behavioral.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards/overall

{
  "reportCard": {
    "overallGrade": "A"
  },
  "tripSampleSize": 1131,
  "gradeCount": {
    "B": "108",
    "F": "1",
    "I": "9",
    "C": "24",
    "A": "1000",
    "D": "1"
  }
}

As you can see, the lifetime report card includes overallGrade... the all time grade for this device. Additionally, the response includes tripSampleSize, which gives you an idea of just how much driving is being factored into the grade. Lastly, the gradeCount object provides a count of trips that received the corresponding grade.

Time Segments

Using since and until query parameters, we make it easy to pull a grade for a given time segment. This is handy if you want to show the user their grade for a the past week/month/day or if you want to give them a period breakdown of their grade over time.

https://behavioral.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards/overall?since=2016-12-05&until=2016-12-13

{
  "reportCard": {
    "overallGrade": "B"
  },
  "tripSampleSize": 50,
  "gradeCount": {
    "B": "108",
    "F": "1",
    "I": "9",
    "C": "24",
    "A": "1001",
    "D": "1"
  }
}

We're excited to see how report cards get surfaced in different connected car applications! Just remember, keep those grades up!