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": {}
}
}
}