Introducing Distance Service

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

Background

Milage, specifically the total milage accumulated over the life of a vehicle (or the odometer reading) is one of the few vehicle datapoints that the OBD-II protocol fails to provide. We've grieved this fact here at Vinli, as milage is often a critical component for building connected car experiences. Milage 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.

Milage 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 travelled 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:

• specific - when an odometer hits a certain distance i.e. 100,000 miles

• from_now - when an odometer hits a certain distance greater than the current distance

• milestone - when an odometer hits a certain recurring interval i.e. every 5k miles

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 milage intervals way easier.

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