Introducing Distance Service

March 23, 2016

We’re proud to announce Distance Service. Our brand new API designed to help developers with odometer/mileage based features.

Background

Mileage, specifically the total mileage accumulated over the life of a vehicle (or the odometer reading) is one of the few vehicle data-points that the OBD-II protocol fails to provide. We’ve grieved this fact here at Vinli, as mileage is often a critical component for building connected car experiences. Mileage is used to schedule service, it’s an important part of tax reporting, and it’s a major factor in calculating the value of a used vehicle.

Mileage is a big deal, and we thought it was important to support the use cases mentioned above… so we invented Distance Service.

How does it work?

Distance Service is not (completely) magic. It needs a baseline reading to kick things off. So we made it super easy to POST odometer readings to the Vinli platform.

POST https://distance.vin.li/api/v1/vehicles/{vehicleId}/odometers
Accept: application/json
Content-Type: application/json

  {
   "odometer": {
    "reading": 29033,
    "date": "2016-02-16T17:01:36.243Z",
    "unit": "km"
   }
  }

Once we have a reading, we’ll start keeping track of the distance traveled by a vehicle so that, in essence, a developer can request the odometer reading at any point (again… as long as it is before the initial reading).

GET https://distance.vin.li/api/v1/vehicles/{vehicleId}/distances

Will return something like:

{
  "distances": [
    {
      "confidenceMin": 38270282.779,
      "confidenceMax": 128122251.041,
      "value": 83196266.91,
      "lastOdometerDate": "2016-02-24T20:59:53.633Z"
      },
    ]
  }

This makes it easy to prompt the user for their odometer reading at natural (and infrequent) check points. Meanwhile, developers can grab an odometer reading as frequently as the need to to power a feature.

Odometer Triggers

Posting and getting odometer readings is fun, but we wanted to add something handy on top of those core features. That’s where Odometer Triggers come in to play.

Distance Service allows developers to define odometer based criteria to trigger events and notifications. Thus, we allow 3 types of triggers:

Events will be created whenever a vehicle’s odometer reading meets the criteria. These links will tell you everything you need to know about Odometer Triggers and Events.

Conclusion

Distance Service fills in nicely for the missing odometer data that OBDII fails to provide. It should make things like appraising the value of a vehicle, establishing a maintenance schedule, or notifying the user at mileage intervals way easier.

It’s a work in progress, so please send any feedback to dev@vin.li or open an issue on Github.

  • engineering