Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
323 lines (263 sloc) 8.93 KB

Distance API

A vehicles Odometer reading is not exposed through the OBDII port. However, knowing this reading can be handy in many use cases... thus we created Distance Service. Distance Service is our best effort guess at what the actual odometer of a car is at present time and/or to provide the milage travelled between 2 points in time.

All distances are in meters.

Get Latest Distance for a Vehicle

This method returns the most current distance estimate for a given vehicle.

Request

GET https://distance.vin.li/api/v1/vehicles/36cf2965-7ed1-4314-8384-f9b6b75a7d3f/distances/_latest
Accept: application/json

Optionally - this method accepts since and until query parameters. You may also pass x-vinli-unit in the header with either km, mi, or m to modify the output units. Defaults to m.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "distance": {
    "vehicleId": "36cf2965-7ed1-4314-8384-f9b6b75a7d3f",
    "value": 94338300.26,
    "unit": "m",
    "confidenceMin": 94337300.26,
    "confidenceMax": 94339300.26,
    "lastOdometerDate": "2016-12-09T23:00:36.755Z",
    "links": {
      "self": "https://distance.vin.li/api/v1/vehicles/36cf2965-7ed1-4314-8384-f9b6b75a7d3f/distances/_latest?since=1970-01-01T00:00:00.000Z&until=2016-12-20T22:29:57.292Z",
      "vehicle": "https://platform.vin.li/api/v1/vehicles/36cf2965-7ed1-4314-8384-f9b6b75a7d3f"
    }
  }
}

Create an Odometer Reading

Request

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

  {
   "odometer": {
    "reading": 15000,
    "date": "2016-04-26T17:01:36.243Z",
    "unit": "km"
   }
  }
  • reading - Required. The odometer value you are submitting.
  • date - The date/time at which this odometer reading applies. Optional, defaults to now.
  • unit - Required. the unit of measure of the reading. Accepts km, mi, or m.

Response

HTTP/1.1 200 OK
Content-Type: application/json

 {
   "odometer": {
     "id": "c6e3fbb7-c1e8-4de3-8c38-75661dd9cd40",
     "vehicleId": "484ceb75-87ba-4813-b414-1c13f2056325",
     "reading": 15000000,
     "unit": "m",
     "date": "2016-12-20T22:35:39.504Z",
     "links": {
       "self": "https://distance.vin.li/api/v1/odometers/c6e3fbb7-c1e8-4de3-8c38-75661dd9cd40",
       "vehicle": "https://platform.vin.li/api/v1/vehicles/484ceb75-87ba-4813-b414-1c13f2056325"
     }
   }
 }

Get All Odometer Readings for a Vehicle

Request

GET https://distance.vin.li/api/v1/vehicles/ec74e512-ed9a-41ae-99e9-779882846b80/odometers
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "odometers": [
  {
    "id": "5b32bcad-a127-40fd-a0f9-c14bc283e255",
    "vehicleId": "ec74e512-ed9a-41ae-99e9-779882846b80",
    "reading": 1720.17,
    "date": "2016-02-09T16:56:31.033Z",
    "links": {
      "self": "https://distance.vin.li/api/v1/odometers/be7baede-c865-3e9c-8181-8126c332683d",
      "vehicle": "https://platform.vin.li/api/v1/vehicles/ec74e512-ed9a-41ae-99e9-779882846b80"
    }
  },
  {
    "id": "59dd31f2-8101-4f1f-9539-6580668e719e",
    "vehicleId": "ec74e512-ed9a-41ae-99e9-779882846b80",
    "reading": 4640.85,
    "date": "2016-02-02T16:56:31.033Z",
    "links": {
      "self": "https://distance.vin.li/api/v1/odometers/be7baede-c865-3e9c-8181-8126c332683d",
      "vehicle": "https://platform.vin.li/api/v1/vehicles/ec74e512-ed9a-41ae-99e9-779882846b80"
    }
  }
],
"meta": {
  "pagination": {
    "remaining": 0,
    "until": "2016-02-16T16:56:31.036Z",
    "since": "1970-01-01T00:00:00.000Z",
    "limit": 20,
    "sortDir": "desc",
    "links": {}
  }
}
}

Get an Odometer

Request

GET https://distance.vin.li/api/v1/odometers/{odometerId}
Accept: application/json

Response

  HTTP/1.1 200 OK
  Content-Type: application/json

{
 "odometer": {
   "id": "bcdc8734-ce79-4d78-a911-f77c09316f5f",
   "vehicleId": "0e14f2db-ff0b-43bd-b88c-01b9f226778f",
   "reading": 83321969.16,
   "date": "2016-03-03T20:23:53.726Z",
   "links": {
     "self": "https://distance.vin.li/api/v1/odometers/bcdc8734-ce79-4d78-a911-f77c09316f5f",
     "vehicle": "https://platform-dev.vin.li/api/v1/vehicles/0e14f2db-ff0b-43bd-b88c-01b9f226778f"
     }
   }
 }

Delete an Odometer Reading

Request

DELETE https://distance.vin.li/api/v1/odometers/bcdc8734-ce79-4d78-a911-f77c09316f5f

Odometer Triggers

Odometer triggers generate events/notifications for milage thresholds that you define.

  • type - Required. There are 3 types of triggers, specific, from_now, milestone
  • specific: when an odometer hits a certain distance i.e. 50k miles
  • from_now: when an odometer hits a specific distance traveled from now
  • milestone: when an odometer hits a certain recurring interval i.e. every 5k miles
  • threshold - Required. The amount for your type.
  • unit - Required. The unit of measure of the threshold. Accepts km, mi, or m.

Once an Odometer Trigger is set, Events will be created when the trigger criteria are met.

Create an Odometer Trigger

Request

POST https://distance.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31/odometer_triggers
Accept: application/json
Content-Type: application/json

{
"odometerTrigger": {
 "type": "specific",
 "threshold": 5000000,
 "unit": "km"
 }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "odometerTrigger": {
    "id": "2b45bf31-b920-4afd-be1f-32b3f867bc4a",
    "vehicleId": "ab4e7199-a3a6-412f-9088-bc05b6d89e31",
    "type": "from_now",
    "threshold": 9496.086,
    "events": 0,
    "links": {
      "self": "https://distance.vin.li/api/v1/odometer_triggers/2b45bf31-b920-4afd-be1f-32b3f867bc4a",
      "vehicle": "https://platform.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31"
    }
  }
}

Get an Odometer Trigger

Request

GET https://distance.vin.li/api/v1/odometer_triggers/2b45bf31-b920-4afd-be1f-32b3f867bc4a

Response

"odometerTrigger": {
 "id": "2b45bf31-b920-4afd-be1f-32b3f867bc4a",
 "vehicleId": "ab4e7199-a3a6-412f-9088-bc05b6d89e31",
 "type": "from_now",
 "threshold": 9496.086,
 "events": 0,
 "links": {
   "self": "https://distance.vin.li/api/v1/odometer_triggers/2b45bf31-b920-4afd-be1f-32b3f867bc4a",
   "vehicle": "https://platform.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31"
 }
}

Delete an Odometer Trigger

Request

DELETE https://distance.vin.li/api/v1/odometer_triggers/2b45bf31-b920-4afd-be1f-32b3f867bc4a

Get All Odometer Triggers for a Vehicle

Request

GET https://distance.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31/odometer_triggers

Response

HTTP/1.1 200 OK
Content-Type: application/json

    {
       "odometerTriggers": [
         {
           "id": "2b45bf31-b920-4afd-be1f-32b3f867bc4a",
           "vehicleId": "ab4e7199-a3a6-412f-9088-bc05b6d89e31",
           "type": "specific",
           "threshold": 5000000000,
           "unit": "m",
           "events": 0,
           "links": {
             "self": "https://distance.vin.li/api/v1/odometer_triggers/2b45bf31-b920-4afd-be1f-32b3f867bc4a",
             "vehicle": "https://platform.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31"
           }
         },
         {
           "id": "6c35bf31-c120-5afd-ae1c-22b3c867fc4f",
           "vehicleId": "ab4e7199-a3a6-412f-9088-bc05b6d89e31",
           "type": "specific",
           "threshold": 5000000000,
           "unit": "m",
           "events": 0,
           "links": {
             "self": "https://distance.vin.li/api/v1/odometer_triggers/6c35bf31-c120-5afd-ae1c-22b3c867fc4f",
             "vehicle": "https://platform.vin.li/api/v1/vehicles/ab4e7199-a3a6-412f-9088-bc05b6d89e31"
           }
         }
       ],
       "meta": {
         "pagination": {
           "remaining": 0,
           "until": "2016-12-20T22:48:48.058Z",
           "since": "1970-01-01T00:00:00.000Z",
           "limit": 20,
           "sortDir": "desc",
           "links": {}
         }
       }
     }