Vinli API Reference¶
Device API¶
List all Devices¶
This returns a paginated list of devices that are registered with your application sorted chronologically by when the device was added.
Request¶
GET https://platform.vin.li/api/v1/devices
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"devices" : [
{
"id" : "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
"name" : "testdevice001",
"links" : {
"self" : "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
"vehicles" : "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/vehicles",
"latestVehicle" : "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/vehicles/_latest"
}
},
...
],
"meta" : {
"pagination" : {
"total" : 1431,
"offset" : 0,
"limit" : 20,
"links" : {
"first" : "https://platform.vin.li/api/v1/devices?offset=0&limit=20",
"last" : "https://platform.vin.li/api/v1/devices?offset=1420&limit=20",
"next" : "https://platform.vin.li/api/v1/devices?offset=20&limit=20"
}
}
}
}
Get a Device¶
Request¶
GET https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"device" : {
"id" : "821374c0-d6d8-11e3-9c1a-0800200c9a66",
"links" : {
"self" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66",
"groups" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/groups",
"vehicles" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles",
"latestVehicle" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles/_latest"
}
}
}
Register a Device¶
Note
This route is only accessible by Enterprise applications. Consumer applications gain and lose devices as users authorize access via the OAuth flow in MyVinli.
Your application may register a device after it has been authorized by the owner of the device (See section above on “Authentication for User Actions”). This step is necessary before your application can access any data from the device or perform any actions on the device.
A two-step process allow you to manage device authorization independent of user action. You can remove a device without requiring a user to revoke access to the device.
Request¶
POST https://platform.vin.li/api/v1/devices
Content-Type: application/json
Accept: application/json
{
"device" : {
"id" : "821374c0-d6d8-11e3-9c1a-0800200c9a66"
}
}
Response¶
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66
{
"device" : {
"id" : "821374c0-d6d8-11e3-9c1a-0800200c9a66",
"links" : {
"self" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66",
"groups" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/groups",
"vehicles" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles",
"latestVehicle" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles/_latest"
}
}
}
Deregister a Device¶
Note
This route is only accessible by Enterprise applications. Consumer applications gain and lose devices as users authorize access via the OAuth flow in MyVinli.
Deregistering a Device from your application prevents you from accessing that device’s data. Note this has several various effects on other section of the Vinli Platform. For instance, Event Services will remove any Rules associated with the device, Safety Services will remove any Emergency Contact actions from the Device (if your application registered the Device with Safety Services), and Diagnostic Services will remove any DTC alerts for this Device registered by your Application.
It’s important to note that deregistering a Device is an Application-level action that will have no effect on any other Application (yours or someone else’s) that has been authorized for the Device.
Request¶
DELETE https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66
Response¶
HTTP/1.1 204 NO CONTENT
Vehicle API¶
List All of a Device’s Vehicles¶
Returns the vehicles associated with the given device in chronological order.
Request¶
GET https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"vehicles" : [
{
"id" : "67e1e940-d6da-11e3-9c1a-0800200c9a66",
"year" : "2007",
"make" : "Toyota",
"model" : "Camry",
"trim" : "SE V6",
"vin" : "2B4GP44R6WR942762",
"links" : {
"self" : "https://platform.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66",
"trips" : "https://trip.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/trips",
"collisions" : "https://safety.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/collisions",
"reportCards" : "https://behavioral.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/reportCards"
}
},
{
"id" : "2a88b0f0-d6db-11e3-9c1a-0800200c9a66",
"vin" : "JE3BW50W4NZ676124",
"links" : {
"self" : "https://platform.vin.li/api/v1/vehicles/2a88b0f0-d6db-11e3-9c1a-0800200c9a66",
"trips" : "https://trip.vin.li/api/v1/vehicles/2a88b0f0-d6db-11e3-9c1a-0800200c9a66/trips",
"collisions" : "https://safety.vin.li/api/v1/vehicles/2a88b0f0-d6db-11e3-9c1a-0800200c9a66/collisions",
"reportCards" : "https://behavioral.vin.li/api/v1/vehicles/2a88b0f0-d6db-11e3-9c1a-0800200c9a66/reportCards"
}
},
...
],
"meta": {
"pagination" : {
"total" : 24,
"limit" : 10,
"offset" : 0,
"links" : {
"first" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles?offset=0&limit=10",
"next" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles?offset=10&limit=10",
"last" : "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles?offset=20&limit=10"
}
}
}
}
List a Device’s Latest Vehicle¶
Returns the vehicle most recently associated with the given device if it exists. If the device has not been associated with a vehicle, a null vehicle object is returned.
Basic vehicle information is returned as part of this response. Follow the vehicle’s “self” link to get full detailed information about the vehicle.
Request¶
GET https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/vehicles/_latest
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"vehicle" : {
"id" : "67e1e940-d6da-11e3-9c1a-0800200c9a66",
"year" : "2007",
"make" : "Toyota",
"model" : "Camry",
"trim" : "SE V6",
"vin" : "2B4GP44R6WR942762",
"links" : {
"self" : "https://platform.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66",
"trips" : "https://trip.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/trips",
"collisions" : "https://safety.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/collisions",
"reportCards" : "https://behavioral.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/reportCards"
}
}
}
Get Information About a Vehicle¶
Returns detailed information about a vehicle. This may include, but is not limitted to:
- Year
- Make
- Model
- Trim
- Engine Information
- Transmission Information
- Available Options
Request¶
GET https://platform.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"vehicle" : {
"id" : "67e1e940-d6da-11e3-9c1a-0800200c9a66",
"year" : "2007",
"make" : "Toyota",
"model" : "Camry",
"trim" : "SE V6",
"vin" : "2B4GP44R6WR942762",
"data" : { ... },
"links" : {
"self" : "https://platform.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66"
}
}
}
Transaction API¶
Get All Transactions for this Application¶
Returns a list of all transactions performed by this Application.
Results are returned in reverse-chronological order, i.e. time series order, using the “Stream Pagination” method.
Request¶
GET https://platform.vin.li/api/v1/transactions
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"transactions" : [
{
"id": "e7924989-e942-4ebb-a566-427984b91af1",
"timestamp": "2015-06-22T00:30:19.455Z",
"path": "/api/v1/devices?limit=1",
"statusCode": 200,
"method": "GET",
"service": "vinli-platform-service"
},
{
"id": "b7d746ce-1794-4796-9dc9-30ae091d1ce6",
"timestamp": "2015-06-20T21:41:13.520Z",
"path": "/api/v1/devices/c38ce5f2-0c4d-4d82-b301-fd87af5fcbd3/locations?limit=20",
"service": "vinli-telemetry-service",
"method": "GET",
"statusCode": 200
},
...
],
"meta" : {
"pagination" : {
"remainingCount" : 1324,
"limit" : 50,
"until" : 1408945415426,
"links" : {
"latest" : "https://platform.vin.li/api/v1/transactions",
"prior" : "https://platform.vin.li/api/v1/transactions?until=1408944636328"
}
}
}
}
Telemetry API¶
Get a List of Telemetry Messages¶
Returns the latest limit number of telemetry messages that occurred before or at the until time and after the since time. If the until time is not specified, then the service will return snapshots until the current time when the call is made.
These messages are sent at least every five seconds and include the latest value of parameters captured by the Vinli device since the last message sent.
Request¶
GET https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/messages
Accept: application/json
- until - Results will contain snapshots whose timestamps are less than or equal to the until value. If an until value is not specified, the current time when the call is made will be used as the until value.
- since - Results will contain snapshots whose timestamps are greater than the since value. If a since value is not specified, no lower limit will be placed on the returned snapshots.
- limit - Results will contain no more than limit number of snapshots
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"messages" : [
{
"id": "2f5f2a7c-02d8-4502-80c6-8cb52d9a08d5",
"timestamp": "2014-07-14T17:46:06.759Z",
"location": {
"longitude": -90.0811,
"latitude": 29.9508
},
"data" : {
"vehicleSpeed": 12,
"calculatedLoadValue": 34.5,
"fuelType": "Gasoline",
"rpm": 1254
}
},
{
"id": "b138303e-e40f-4d02-88a5-df41ca50ea3c",
"timestamp": "2014-07-14T17:46:01.544Z",
"location": {
"longitude": -90.0813,
"latitude": 29.950802
},
"data" : {
"vehicleSpeed": 15,
"rpm": 1766
}
},
{
"id": "fff266e2-deb3-4d3d-b181-bd0f048ce20c",
"timestamp": "2014-07-14T17:45:54.872Z",
"location": {
"longitude": -90.08104,
"latitude": 29.950813
},
"data" : {
"vehicleSpeed": 16,
"calculatedLoadValue": 56.3,
"rpm": 1486
}
}
...
],
"meta" : {
"pagination" : {
"remainingCount" : 1324,
"limit" : 50,
"until" : 1394733261450,
"links" : {
"latest" : "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/messages"
"prior" : "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/messages?until=1394733251897"
}
}
}
}
Get a Specific Telemetry Message¶
Returns a particular message by messageId. This is primarily used when a specific message is referenced by a different service.
Request¶
GET https://telemetry.vin.li/api/v1/messages/2f11d630-141e-11e4-b717-5977b6c38d23
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"message" : {
"id" : "27a2ac50-d7bd-11e3-9c1a-0800200c9a66",
"timestamp": "2014-07-14T17:46:06.759Z",
"data": {
"location": {
"type": "point",
"coordinates": [
-90.0811,
29.9508
]
},
"vehicleSpeed": 0
},
"links" : {
self": "https://telemetry.vin.li/api/v1/messages/2f11d630-141e-11e4-b717-5977b6c38d23"
}
}
}
Locations¶
Returns the latest limit number of points of the device’s location before or at the until time and after the since time. If the until time is not specified, then the service will return snapshots until the current time when the call is made. The location property contains a valid GeoJSON FeatureCollection object consisting of Point features for each location. The timestamp for each location is the in the properties field of the feature.
Additionally, selected or all parameters that were recorded at each location can also be included in the properties field. When all is specified, this method acts just like the Device Messages method below, but it is formatted as valid GeoJSON.
Request¶
GET https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/locations?fields=rpm,vehicleSpeed
Accept: application/json
- fields - Can be all or a comma-separated list of parameter keys to be included in the properties field.
- until - Results will contain snapshots whose timestamps are less than or equal to the until value. If an until value is not specified, the current time when the call is made will be used as the until value.
- since - Results will contain snapshots whose timestamps are greater than the since value. If an since value is not specified, no lower limit will be placed on the returned snapshots.
- limit - Results will contain no more than limit number of snapshots
Response¶
{
"locations" : {
"type" : "FeatureCollection",
"features" : [
{
"type" : "Feature",
"geometry" : {
"type" : "Point",
"coordinates" : [-90.0811, 29.9508]
},
"properties" : {
"timestamp" : "2014-03-13T17:54:20.050Z",
"rpm" : 1264,
"vehicleSpeed" : 54
}
},
{
"type" : "Feature",
"geometry" : {
"type" : "Point",
"coordinates" : [-90.08198, 29.9498]
},
"properties" : {
"timestamp" : "2014-03-13T17:54:07.122Z",
"rpm" : 1832
}
},
...
]
},
"meta" : {
"pagination" : {
"remaining" : 2341,
"limit" : 200,
"until" : 1394733260050,
"links" : {
"prior" : "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/locations?until=1394733247121"
}
}
}
}
Telemetry Snapshots¶
Returns the latest limit number of telemetry snapshots that contain at least one of the requested parameters that occurred before or at the until time and after the since time. If the until time is not specified, then the service will return snapshots until the current time when the call is made.
Request¶
GET https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?fields=rpm,vehicleSpeed,calculatedLoadValue,fuelType
Accept: application/json
- fields - Comma-separated list of parameter keys to filter by
- until - Results will contain snapshots whose timestamps are less than or equal to the until value. If an until value is not specified, the current time when the call is made will be used as the until value.
- since - Results will contain snapshots whose timestamps are greater than the since value. If a since value is not specified, no lower limit will be placed on the returned snapshots.
- limit - Results will contain no more than limit number of snapshots
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"snapshots": [
{
"timestamp": 1394733260050,
"data": {
"vehicleSpeed": 12,
"calculatedLoadValue": 34.5,
"fuelType": "Gasoline"
}
},
{
"timestamp": 1394733255337,
"data": {
"vehicleSpeed": 15
}
},
{
"timestamp": 1394733251898,
"data": {
"rpm": 3827,
"calculatedLoadValue": 56.3
}
}
],
"meta": {
"pagination": {
"remainingCount": 1324,
"limit": 50,
"until": 1394733261450,
"links": {
"latest": "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?fields=rpm,vehicleSpeed,calculatedLoadValue,fuelType",
"prior": "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?fields=rpm,vehicleSpeed,calculatedLoadValue,fuelType&until=1394733251897"
}
}
}
}
Event API¶
Get All Events for a Device¶
Returns the list all events for a given Device in reverse-chronological order. Each Event contains information regarding the device, the object involved in the event, and associated metadata.
The following fields are contained within an event response:
- id - ID of the event
- timestamp - Timestamp when the event occurred
- deviceId - ID of the device
- eventType - Type of event
- object - Information about the object of the event (i.e. the associated Rule or Vehicle)
- meta - Optional data depending on the type of event. For instance, for a rule-enter or rule-leave event, the meta property contains information about the Rule itself and the state and direction of the event.
- links - object containing links to associated data
Request¶
GET https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events
Accept: application/json
Parameters¶
- type - (optional) filter events for those of a given type
- until - Results will contain events whose timestamps are less than or equal to the until value. If an until value is not specified, the current time when the call is made will be used as the until value.
- since - Results will contain events whose timestamps are greater than the since value. If an since value is not specified, no lower limit will be placed on the returned events.
- limit - Results will contain no more than limit number of events
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"events": [
{
"id": "538f1195-a733-4ee7-a4e8-1fbbe7131f6a",
"timestamp": "2015-05-22T23:33:57.000Z",
"deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
"stored": "2015-05-22T23:33:58.741Z",
"storageLatency": 1741,
"eventType": "rule-leave",
"meta": {
"direction": "leave",
"firstEval": false,
"rule": {
"id": "429f9aa7-4c97-42c1-a459-ee1df6bc625b",
"name": "Speed Limit",
"deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
"boundaries": [
{
"id": "0cadb0c8-a1c3-4176-86f2-20280ea72ad9",
"type": "parametric",
"parameter": "vehicleSpeed",
"min": 48
}
],
"evaluated": true,
"covered": false,
"createdAt": null,
"links": {
"self": "https://rules.vin.li/api/v1/rules/429f9aa7-4c97-42c1-a459-ee1df6bc625b"
}
},
"message": {
"id": "60afa670-d15b-4d2f-81bf-a068f4a9a7fb",
"timestamp": "2015-05-22T23:33:57.000Z",
"snapshot": {
"location": {
"lat": 33.0246240995378,
"lon": -97.0560955928522
},
"vehicleSpeed": 32
}
}
},
"object": {
"id": "429f9aa7-4c97-42c1-a459-ee1df6bc625b",
"type": "rule",
"appId": "b75afd8f-7247-46e6-a0f9-04f187c9d9bd"
},
"links": {
"self": "https://events.vin.li/api/v1/events/538f1195-a733-4ee7-a4e8-1fbbe7131f6a",
"notifications": "https://events.vin.li/api/v1/events/538f1195-a733-4ee7-a4e8-1fbbe7131f6a/notifications"
}
},{
"id": "53bcdb2f-7a75-4225-ac15-b2d4364d9c7b",
"timestamp": "2015-05-22T18:25:43.000Z",
"deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
"stored": "2015-05-22T18:25:44.609Z",
"storageLatency": 1609,
"eventType": "startup",
"object": {
"id": "5956bc07-be98-4af5-91cc-86816aca7eb0",
"type": "vehicle"
},
"links": {
"self": "https://events.vin.li/api/v1/events/53bcdb2f-7a75-4225-ac15-b2d4364d9c7b",
"notifications": "https://events.vin.li/api/v1/events/53bcdb2f-7a75-4225-ac15-b2d4364d9c7b/notifications"
}
}
],
"meta": {
"pagination": {
"remaining": 109,
"limit": 2,
"until": "2015-05-25T15:23:26.933Z",
"links": {
"prior": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?until=2015-05-22T20%3A13%3A49.999Z"
}
}
}
}
Get a Specific Event¶
Returns information about a specific event.
Request¶
GET https://events.vin.li/api/v1/events/538f1195-a733-4ee7-a4e8-1fbbe7131f6a
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"event": {
"id": "538f1195-a733-4ee7-a4e8-1fbbe7131f6a",
"timestamp": "2015-05-22T23:33:57.000Z",
"deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
"stored": "2015-05-22T23:33:58.741Z",
"storageLatency": 1741,
"eventType": "rule-leave",
"meta": {
"direction": "leave",
"firstEval": false,
"rule": {
"id": "429f9aa7-4c97-42c1-a459-ee1df6bc625b",
"name": "Speed Limit",
"deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
"boundaries": [
{
"id": "0cadb0c8-a1c3-4176-86f2-20280ea72ad9",
"type": "parametric",
"parameter": "vehicleSpeed",
"min": 48
}
],
"evaluated": true,
"covered": false,
"createdAt": null,
"links": {
"self": "https://rules.vin.li/api/v1/rules/429f9aa7-4c97-42c1-a459-ee1df6bc625b"
}
},
"message": {
"id": "60afa670-d15b-4d2f-81bf-a068f4a9a7fb",
"timestamp": "2015-05-22T23:33:57.000Z",
"snapshot": {
"location": {
"lat": 33.0246240995378,
"lon": -97.0560955928522
},
"vehicleSpeed": 32
}
}
},
"object": {
"id": "429f9aa7-4c97-42c1-a459-ee1df6bc625b",
"type": "rule",
"appId": "b75afd8f-7247-46e6-a0f9-04f187c9d9bd"
},
"links": {
"self": "https://events.vin.li/api/v1/events/538f1195-a733-4ee7-a4e8-1fbbe7131f6a",
"notifications": "https://events.vin.li/api/v1/events/538f1195-a733-4ee7-a4e8-1fbbe7131f6a/notifications"
}
}
}
Subscriptions¶
In order to receive notification for vehicle events, your application must subscribe to events for each device individually.
Each Subscription relates to a given event or class of events from a given Device and specifies the external URL that will be called when the event occurs and any additional “App Data” that should be included.
Notification Payload¶
When a subscription is triggered, an HTTP call using the “POST” method is made to the Subscription’s URL. This call uses content-type of “application/json” and sends a JSON representation containing a notification root object along with representations of the Event that triggered the notification and the associated Subscription:
{
"notification": {
"event": {
"id": "314d7fcd-d4d6-4b78-9804-b171db60790a",
"timestamp": "2015-06-16T13:12:34.000Z",
"deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
"eventType": "rule-leave",
"object": {
"id": "79f2e013-b6b9-44dd-9f34-4be5da971d7a",
"type": "rule",
"appId": "b75afd8f-7247-46e6-a0f9-04f187c9d9bd"
},
"meta": {
"direction": "leave",
"firstEval": false,
"rule": {
"id": "79f2e013-b6b9-44dd-9f34-4be5da971d7a",
"name": "My Geofence",
"deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
"boundaries": [],
"evaluated": true,
"covered": false,
"createdAt": "2015-06-16T12:54:09.601Z",
"links": {
"self": "https://rules.vin.li/api/v1/rules/79f2e013-b6b9-44dd-9f34-4be5da971d7a",
"events": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events?type=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a",
"subscriptions": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions?objectType=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a"
}
},
"message": {
"id": "cd339f3d-b0d8-49a9-a87d-ca7ee3a937e2",
"timestamp": "2015-06-16T13:12:34.000Z",
"snapshot": {
"location": {
"lat": 32.5536468870112,
"lon": -96.1153222519258
}
}
}
}
},
"subscription": {
"id": "a896ff7d-ca46-4bf4-af71-b9b1573c3ef1",
"deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
"eventType": "rule-leave",
"url": "https://myapp.com/notifications",
"object": {
"id": "79f2e013-b6b9-44dd-9f34-4be5da971d7a",
"type": "rule"
},
"appData": "{\"message\":\"This is your app-specific data\"}"
}
}
}
Note that the appData attribute of the subscription property contains the Application-specific data that you created the Subscription with, if applicable.
In the example above, the Subscription triggered is associated with a Rule. In this case, additional information is made available in the Notificaiton including a reprsentation of the Rule in the meta property. Additionally, a very useful property firstEval is provided that lets your Application know whether or not this is the first evaluation of the Rule. The first evaluation of a Rule in which it can be established that the device is covered or not covered by the boundaries will always result in a notification. Using the firstEval property, your App can determine if the device was previously in a different state or was just in an unknown state.
Create a Subscription¶
A Subscription must include, at a minimum an eventType and a url. Additionally, if the subscription references a given Rule, it must be included in the object.
Request¶
POST https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions
Accept: application/json
Content-Type: application/json
{
"subscription" : {
"eventType" : "startup",
"url": "https://myapp.com/notifications"
}
}
Response¶
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://events.vin.li/api/v1/subscriptions/77965f0f-d468-48e1-9585-69d547900058
{
"subscription" : {
"id": "77965f0f-d468-48e1-9585-69d547900058",
"deviceId": "de01abb1-453d-4293-831a-f0d804b48fdf",
"eventType": "startup",
"url": "https://myapp.com/notifications",
"createdAt": "2015-06-16T12:54:09.876Z",
"updatedAt": "2015-06-16T12:54:09.876Z",
"links": {
"self": "https://events.vin.li/api/v1/subscriptions/77965f0f-d468-48e1-9585-69d547900058",
"notifications": "https://events.vin.li/api/v1/subscriptions/77965f0f-d468-48e1-9585-69d547900058/notifications"
}
}
}
When creating a Subscription to a Rule’s events, identification of the Rule is required. An application can only subscribe to Rule events for Rules to which it has access. A special eventType (rule-*) can be used to subscribe to both rule-enter and rule-leave events.
Also note that in the example below, appData is given so that this is passed on to the App whenever the subscription is triggered.
Request¶
POST https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions
Accept: application/json
Content-Type: application/json
{
"subscription" : {
"eventType" : "rule-*",
"url": "https://myapp.com/notifications",
"appData": "{\"message\":\"This is your app-specific data\"}",
"object": {
"id": "41d68c9e-2914-4923-8593-3abdf299537c",
"type": "rule"
}
}
}
Response¶
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b
{
"subscription" : {
"id": "917fb546-5666-4fdd-aed6-53fa099b313b",
"deviceId": "de01abb1-453d-4293-831a-f0d804b48fdf",
"eventType": "rule-*",
"object": {
"id": "58f815b9-693d-450a-8814-779c9bf8ad6f",
"type": "rule"
},
"url": "https://myapp.com/notifications",
"appData": "{\"message\":\"This is your app-specific data\"}"
"createdAt": "2015-06-16T12:54:09.876Z",
"updatedAt": "2015-06-16T12:54:09.876Z",
"links": {
"self": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b",
"notifications": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b/notifications"
}
}
}
Get all Subscriptions for a Device¶
Request¶
GET https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscriptions": [
{
"id": "917fb546-5666-4fdd-aed6-53fa099b313b",
"deviceId": "de01abb1-453d-4293-831a-f0d804b48fdf",
"eventType": "rule-*",
"object": {
"id": "58f815b9-693d-450a-8814-779c9bf8ad6f",
"type": "rule"
},
"url": "https://myapp.com/notifications",
"appData": "{\"message\":\"This is your app-specific data\"}"
"createdAt": "2015-06-16T12:54:09.876Z",
"updatedAt": "2015-06-16T12:54:09.876Z",
"links": {
"self": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b",
"notifications": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b/notifications"
}
},
...
],
"meta": {
"pagination": {
"total": 70,
"limit": 20,
"offset": 0,
"links": {
"first": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?offset=0&limit=20",
"last": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?offset=60&limit=20",
"next": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?offset=20&limit=20"
}
}
}
}
Get a Specific Subscription¶
Request¶
GET https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription": {
"id": "917fb546-5666-4fdd-aed6-53fa099b313b",
"deviceId": "de01abb1-453d-4293-831a-f0d804b48fdf",
"eventType": "rule-*",
"object": {
"id": "58f815b9-693d-450a-8814-779c9bf8ad6f",
"type": "rule"
},
"url": "https://myapp.com/notifications",
"appData": "{\"message\":\"This is your app-specific data\"}"
"createdAt": "2015-06-16T12:54:09.876Z",
"updatedAt": "2015-06-16T12:54:09.876Z",
"links": {
"self": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b",
"notifications": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b/notifications"
}
}
}
Update a Subscription¶
Subscriptions are primarily immutable. The url and appData properties can be updated; however, the “functional” parts of the Subscription (eventType, object, etc.) are not modifiable.
Request¶
POST https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions
Accept: application/json
Content-Type: application/json
{
"subscription" : {
"url": "https://myapp.com/v2/notifications",
"appData": "{\"message\":\"This is updated app-specific data\"}",
}
}
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"subscription" : {
"id": "917fb546-5666-4fdd-aed6-53fa099b313b",
"deviceId": "de01abb1-453d-4293-831a-f0d804b48fdf",
"eventType": "rule-*",
"object": {
"id": "58f815b9-693d-450a-8814-779c9bf8ad6f",
"type": "rule"
},
"url": "https://myapp.com/v2/notifications",
"appData": "{\"message\":\"This is updated app-specific data\"}",
"createdAt": "2015-06-16T12:54:09.876Z",
"updatedAt": "2015-06-16T12:54:09.876Z",
"links": {
"self": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b",
"notifications": "https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b/notifications"
}
}
}
Delete a Subscription¶
Request¶
DELETE https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b
Accept: application/json
Response¶
HTTP/1.1 204 NO CONTENT
Notifications¶
Each time a subscription is triggered by an event, a new Notification is created that represents the event, subscription, and subsequent actions taken by the Vinli platform to notify your application.
Notification state is useful in debugging notification handlers on your App. This state, responseCode, and response properties will inform you as to the result of Event Services’ attempt to call the notification URL. A notification will be linked to one subscription and may contain additional metadata depending on the trigger of the subscription. In the case of subscriptions to Rules, this metadata
Fields included in a notification response include:
- id - ID of the notification
- eventId - ID of the event that triggered the notification
- eventType - Type of the associated event
- eventTimestamp - Time that the associated event occurred
- subscriptionId - ID of the subscription that this notification is associated with
- url - URL that was called by Event Service; this is copied from the subscription at the creation of the notification
- payload - String of the payload exactly as it was posted to the above URL
- state - Current state of the notification. State values may include created, queued, complete, or error
The state of a notification start as created and moves to queued as soon as it is placed in the notification queue to be processed. Once the notification has been posted to the callback URL, the state will be moved to complete if the HTTP transaction was completed and a response code in the 200s was received. If the HTTP call is not able to be completed or a response code other than the 200s, the state will become error.
If the notification is in the complete or error state, the fields below will be available in the response:
- responseCode - HTTP code received from the URL above
- response - String of the response from the URL above
- notifiedAt - Time that the HTTP call was initiated
- respondedAt - Time that the HTTP call was completed (if successful)
Get a Specific Notification¶
Request¶
GET https://events.vin.li/api/v1/notifications/09704b59-83d9-44a5-a0f8-33d973bdac5e
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"notification": {
"id": "09704b59-83d9-44a5-a0f8-33d973bdac5e",
"eventId": "314d7fcd-d4d6-4b78-9804-b171db60790a",
"eventType": "rule-leave",
"eventTimestamp": "2015-06-16T13:12:34.000Z",
"subscriptionId": "a896ff7d-ca46-4bf4-af71-b9b1573c3ef1",
"state": "complete",
"responseCode": 201,
"response": "{\"status\":\"success\"}",
"url": "https://myapp.com/notifications",
"payload": "{\"notification\":{\"event\":{\"id\":\"314d7fcd-d4d6-4b78-9804-b171db60790a\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"stored\":\"2015-06-16T13:12:35.825Z\",\"storageLatency\":1825,\"eventType\":\"rule-leave\",\"meta\":{\"direction\":\"leave\",\"firstEval\":false,\"rule\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"name\":\"[geofence] Marlee\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"boundaries\":[],\"evaluated\":true,\"covered\":false,\"createdAt\":\"2015-06-16T12:54:09.601Z\",\"links\":{\"self\":\"https://rules.vin.li/api/v1/rules/79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"events\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events?type=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"subscriptions\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions?objectType=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\"}},\"message\":{\"id\":\"cd339f3d-b0d8-49a9-a87d-ca7ee3a937e2\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"snapshot\":{\"location\":{\"lat\":32.5536468870112,\"lon\":-96.1153222519258}}}},\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\",\"appId\":\"b75afd8f-7247-46e6-a0f9-04f187c9d9bd\"}},\"subscription\":{\"id\":\"a896ff7d-ca46-4bf4-af71-b9b1573c3ef1\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"eventType\":\"rule-leave\",\"url\":\"https://myapp.com/notifications\",\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\"},\"appData\":\"{\\\"message\\\":\\\"This is your app-specific data\\\"}\"}}}",
"notifiedAt": "2015-06-16T13:12:35.862Z",
"respondedAt": "2015-06-16T13:12:36.300Z",
"createdAt": "2015-06-16T13:12:35.842Z",
"links": {
"self": "https://events.vin.li/api/v1/notifications/09704b59-83d9-44a5-a0f8-33d973bdac5e",
"event": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events/314d7fcd-d4d6-4b78-9804-b171db60790a",
"subscription": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1"
}
}
}
Get Notifications for a Subscription¶
Request¶
GET https://events.vin.li/api/v1/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1/notifications
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"notifications": [
{
"id": "09704b59-83d9-44a5-a0f8-33d973bdac5e",
"eventId": "314d7fcd-d4d6-4b78-9804-b171db60790a",
"eventType": "rule-leave",
"eventTimestamp": "2015-06-16T13:12:34.000Z",
"subscriptionId": "a896ff7d-ca46-4bf4-af71-b9b1573c3ef1",
"state": "complete",
"responseCode": 201,
"response": "{\"status\":\"success\"}",
"url": "https://myapp.com/notifications",
"payload": "{\"notification\":{\"event\":{\"id\":\"314d7fcd-d4d6-4b78-9804-b171db60790a\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"stored\":\"2015-06-16T13:12:35.825Z\",\"storageLatency\":1825,\"eventType\":\"rule-leave\",\"meta\":{\"direction\":\"leave\",\"firstEval\":false,\"rule\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"name\":\"[geofence] Marlee\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"boundaries\":[],\"evaluated\":true,\"covered\":false,\"createdAt\":\"2015-06-16T12:54:09.601Z\",\"links\":{\"self\":\"https://rules.vin.li/api/v1/rules/79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"events\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events?type=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"subscriptions\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions?objectType=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\"}},\"message\":{\"id\":\"cd339f3d-b0d8-49a9-a87d-ca7ee3a937e2\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"snapshot\":{\"location\":{\"lat\":32.5536468870112,\"lon\":-96.1153222519258}}}},\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\",\"appId\":\"b75afd8f-7247-46e6-a0f9-04f187c9d9bd\"}},\"subscription\":{\"id\":\"a896ff7d-ca46-4bf4-af71-b9b1573c3ef1\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"eventType\":\"rule-leave\",\"url\":\"https://myapp.com/notifications\",\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\"},\"appData\":\"{\\\"message\\\":\\\"This is your app-specific data\\\"}\"}}}",
"notifiedAt": "2015-06-16T13:12:35.862Z",
"respondedAt": "2015-06-16T13:12:36.300Z",
"createdAt": "2015-06-16T13:12:35.842Z",
"links": {
"self": "https://events.vin.li/api/v1/notifications/09704b59-83d9-44a5-a0f8-33d973bdac5e",
"event": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events/314d7fcd-d4d6-4b78-9804-b171db60790a",
"subscription": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1"
}
}
],
"meta": {
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"links": {
"first": "https://events.vin.li/api/v1/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1/notifications?offset=0&limit=20",
"last": "https://events.vin.li/api/v1/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1/notifications?offset=0&limit=20"
}
}
}
}
Get Notifications for an Event¶
Returns the notifications that were triggered for any subscription associated with a given event.
Request¶
GET https://events.vin.li/api/v1/events/314d7fcd-d4d6-4b78-9804-b171db60790a/notifications
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"notifications": [
{
"id": "09704b59-83d9-44a5-a0f8-33d973bdac5e",
"eventId": "314d7fcd-d4d6-4b78-9804-b171db60790a",
"eventType": "rule-leave",
"eventTimestamp": "2015-06-16T13:12:34.000Z",
"subscriptionId": "a896ff7d-ca46-4bf4-af71-b9b1573c3ef1",
"state": "complete",
"responseCode": 201,
"response": "{\"status\":\"success\"}",
"url": "https://myapp.com/notifications",
"payload": "{\"notification\":{\"event\":{\"id\":\"314d7fcd-d4d6-4b78-9804-b171db60790a\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"stored\":\"2015-06-16T13:12:35.825Z\",\"storageLatency\":1825,\"eventType\":\"rule-leave\",\"meta\":{\"direction\":\"leave\",\"firstEval\":false,\"rule\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"name\":\"[geofence] Marlee\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"boundaries\":[],\"evaluated\":true,\"covered\":false,\"createdAt\":\"2015-06-16T12:54:09.601Z\",\"links\":{\"self\":\"https://rules.vin.li/api/v1/rules/79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"events\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events?type=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"subscriptions\":\"https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions?objectType=rule&objectId=79f2e013-b6b9-44dd-9f34-4be5da971d7a\"}},\"message\":{\"id\":\"cd339f3d-b0d8-49a9-a87d-ca7ee3a937e2\",\"timestamp\":\"2015-06-16T13:12:34.000Z\",\"snapshot\":{\"location\":{\"lat\":32.5536468870112,\"lon\":-96.1153222519258}}}},\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\",\"appId\":\"b75afd8f-7247-46e6-a0f9-04f187c9d9bd\"}},\"subscription\":{\"id\":\"a896ff7d-ca46-4bf4-af71-b9b1573c3ef1\",\"deviceId\":\"4bffefbb-9fba-43ee-aebe-ed7f7f2fae84\",\"eventType\":\"rule-leave\",\"url\":\"https://myapp.com/notifications\",\"object\":{\"id\":\"79f2e013-b6b9-44dd-9f34-4be5da971d7a\",\"type\":\"rule\"},\"appData\":\"{\\\"message\\\":\\\"This is your app-specific data\\\"}\"}}}",
"notifiedAt": "2015-06-16T13:12:35.862Z",
"respondedAt": "2015-06-16T13:12:36.300Z",
"createdAt": "2015-06-16T13:12:35.842Z",
"links": {
"self": "https://events.vin.li/api/v1/notifications/09704b59-83d9-44a5-a0f8-33d973bdac5e",
"event": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/events/314d7fcd-d4d6-4b78-9804-b171db60790a",
"subscription": "https://events.vin.li/api/v1/devices/4bffefbb-9fba-43ee-aebe-ed7f7f2fae84/subscriptions/a896ff7d-ca46-4bf4-af71-b9b1573c3ef1"
}
}
],
"meta": {
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"links": {
"first": "https://events.vin.li/api/v1/events/314d7fcd-d4d6-4b78-9804-b171db60790a/notifications?offset=0&limit=20",
"last": "https://events.vin.li/api/v1/events/314d7fcd-d4d6-4b78-9804-b171db60790a/notifications?offset=0&limit=20"
}
}
}
}
Diagnostic API¶
List all DTC Codes for a Device¶
The DTC History Service provides historical information for DTC codes for a given vehicle. Each time a new DTC code is seen, it triggers a DTC Event. These events either resolve when the DTC code is no longer seen or remain “open” until the code is resolved.
Request¶
GET https://diagnostic.vin.li/api/v1/vehicles/47fa348e-c3fa-4cad-8272-61940eae7748/codes
Accept: application/json
The state query param may be used to filter the response. Valid values are active and inactive. These will filter the response to only include either DTC codes that are still on presently or not. The absence of the state query param will not filter the response and so the response will contain the full history DTC codes.
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"codes": [
{
"id": "dd46be07-24d0-48ad-be76-c459d35661ed",
"deviceId": "397c302b-b083-4e5f-940b-15824b228e0b",
"vehicleId": "7e94bdb6-7578-484d-99f5-37dec3e172b6",
"number": "P0102",
"description": "Mass or Volume Air Flow Sensor \"A\" Circuit Low",
"start": "2015-12-01T19:58:58.279Z",
"stop": null,
"links": {
"code": "http://diagnostic.vin.li/api/v1/codes/27268249-a716-402c-8550-7fc0d4ae6335",
"device": "http://platform.vin.li/api/v1/devices/397c302b-b083-4e5f-940b-15824b228e0b",
"vehicle": "http://platform.vin.li/api/v1/vehicles/7e94bdb6-7578-484d-99f5-37dec3e172b6"
}
},
{
"id": "02ad82a5-f6e6-4957-8f65-bc791d7399ae",
"deviceId": "397c302b-b083-4e5f-940b-15824b228e0b",
"vehicleId": "7e94bdb6-7578-484d-99f5-37dec3e172b6",
"number": "P0101",
"description": "Mass or Volume Air Flow Sensor \"A\" Circuit Range/Performance",
"start": "2015-12-01T19:58:58.279Z",
"stop": null,
"links": {
"code": "http://diagnostic.vin.li/api/v1/codes/a5cc128c-9a9b-487d-a6dd-375a9cc62dc4",
"device": "http://platform.vin.li/api/v1/devices/397c302b-b083-4e5f-940b-15824b228e0b",
"vehicle": "http://platform.vin.li/api/v1/vehicles/7e94bdb6-7578-484d-99f5-37dec3e172b6"
}
},
{
"id": "91e105ab-4f65-434e-8f41-088735299319",
"deviceId": "397c302b-b083-4e5f-940b-15824b228e0b",
"vehicleId": "7e94bdb6-7578-484d-99f5-37dec3e172b6",
"number": "P0100",
"description": "Mass or Volume Air Flow Sensor \"A\" Circuit",
"start": "2015-12-01T19:58:58.279Z",
"stop": null,
"links": {
"code": "http://diagnostic.vin.li/api/v1/codes/88853bda-e43e-4f60-bd72-8083ff02c85f",
"device": "http://platform.vin.li/api/v1/devices/397c302b-b083-4e5f-940b-15824b228e0b",
"vehicle": "http://platform.vin.lid/api/v1/vehicles/7e94bdb6-7578-484d-99f5-37dec3e172b6"
}
}
],
"meta": {
"pagination": {
"remaining": 0,
"until": "2015-12-01T19:58:58.761Z",
"since": "1970-01-01T00:00:00.000Z",
"limit": 20,
"sortDir": "desc",
"links": {}
}
}
}
DTC Info Service¶
Get DTC Code Information¶
There’s a lot of information encoded in the DTC codes reported by a Vehicle. This method is meant to provide this information for a given DTC code so that your Application can present useful information to the end-user.
Request¶
GET https://diagnostic.vin.li/api/v1/codes?number=P0001
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"codes": [
{
"id": "2db60bc5-0548-43ee-91c0-c34d59ce71ce",
"make": "generic",
"system": "powertrain",
"subSystem": "Fuel and air metering",
"number": "P0001",
"description": "Fuel Volume Regulator Control Circuit/Open",
"links": {
"self": "http://diagnostic.vin.li/api/v1/codes/2db60bc5-0548-43ee-91c0-c34d59ce71ce"
}
}
],
"meta": {
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"links": {
"first": "http://diagnostic.vin.li/api/v1/codes?offset=0&limit=20",
"last": "http://diagnostic.vin.li/api/v1/codes?offset=0&limit=20"
}
}
}
}
Trip API¶
List All of a Device’s Trips¶
This method returns a list of all trips that a given device has taken. This will include trips that have not yet been completed.
Request¶
GET https://trips.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/trips
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
"trips: [
{
"id": "a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"start": "2015-08-19T19:25:15.951Z",
"stop": "2015-08-19T19:35:28.875Z",
"status": "completed",
"vehicleId": "0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"startPoint": {
"type": "Point",
"coordinates": [
-96.789791,
32.780046
]
},
"stopPoint": {
"type": "Point",
"coordinates": [
-96.791057,
32.780671
]
},
"preview": "ijagEdgwmQtC}B`@Q^w@\\U?ICCBA@BFGBKFIB@OLBCm@cBa@u@W[Uo@c@i@Oq@]_@MCw@z@W?F\\?Fd@c@t@a@f@Td@h@b@n@`@v@`@`@b@n@@?CCEFJv@^lATjAHpA@hAH|@Tz@RvAJd@E^U\\eBbCi@l@WTKl@De@?L@AKPy@z@i@b@Yl@u@jAAPU?sAJmADM[g@aCAgCGIEDJm@h@Q`@ICDGA]kAK}@Yy@Bs@Ve@V[f@M^PVb@Ah@CNSXSGAKBGFD",
"stats": {
"averageLoad": 42.6683,
"averageMovingSpeed": 23.1505,
"averageSpeed": 15.4892,
"comprehensiveLocations": true,
"distance": 2125.35,
"distanceByGPS": 2051.44,
"distanceByVSS": 2125.35,
"duration": 612924,
"fuelConsumed": 0.358368,
"fuelEconomy": 15.277,
"hardAccelCount": null,
"hardBrakeCount": null,
"locationCount": 160,
"maxSpeed": 47,
"messageCount": 182,
"stdDevMovingSpeed": 11.0187,
"stopCount": 8,
"substantial": true
},
"links": {
"self": "https://trips.vin.li/api/v1/trips/a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"vehicle": "https://platform.vin.li/api/v1/vehicles/0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"locations": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/locations?since=1440012315951&until=1440012928875",
"messages": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/messages?since=1440012315951&until=1440012928875",
"events": "https://events.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/events?since=1440012315951&until=1440012928875"
}
}
],
"meta": {
"pagination": {
"remaining": 1,
"until": "2015-06-19T23:59:59.000Z",
"since": "1970-01-01T00:00:00.000Z",
"limit": 20,
"sortDir": "desc",
"links": {
"prior": "https://trips-dev.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/trips?until=1434129972999"
}
}
}
List All of a Vehicle’s Trips¶
This method returns a list of all trips that a given vehicle has taken. This will include trips that have not yet been completed. This list will include only trips for the vehicle for which the current application has access to the associated device.
Please note, that trips are sometimes created asynchronously–either because they have to be constructed by post-processing or after bulk data upload for a given device.
Request¶
GET https://trips.vin.li/api/v1/vehicles/0c785aa0-1a48-4cc6-9f5c-028350dd907d/trips
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"trips": [
{
"id": "a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"start": "2015-08-19T19:25:15.951Z",
"stop": "2015-08-19T19:35:28.875Z",
"status": "completed",
"vehicleId": "0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"startPoint": {
"type": "Point",
"coordinates": [
-96.789791,
32.780046
]
},
"stopPoint": {
"type": "Point",
"coordinates": [
-96.791057,
32.780671
]
},
"preview": "ijagEdgwmQtC}B`@Q^w@\\U?ICCBA@BFGBKFIB@OLBCm@cBa@u@W[Uo@c@i@Oq@]_@MCw@z@W?F\\?Fd@c@t@a@f@Td@h@b@n@`@v@`@`@b@n@@?CCEFJv@^lATjAHpA@hAH|@Tz@RvAJd@E^U\\eBbCi@l@WTKl@De@?L@AKPy@z@i@b@Yl@u@jAAPU?sAJmADM[g@aCAgCGIEDJm@h@Q`@ICDGA]kAK}@Yy@Bs@Ve@V[f@M^PVb@Ah@CNSXSGAKBGFD",
"stats": {
"averageLoad": 42.6683,
"averageMovingSpeed": 23.1505,
"averageSpeed": 15.4892,
"distance": 2125.35,
"distanceByGPS": 2051.44,
"distanceByVSS": 2125.35,
"duration": 612924,
"fuelConsumed": 0.358368,
"fuelEconomy": 15.277,
"hardAccelCount": null,
"hardBrakeCount": null,
"locationCount": 160,
"maxSpeed": 47,
"messageCount": 182,
"stdDevMovingSpeed": 11.0187,
"stopCount": 8
},
"links": {
"self": "https://trips.vin.li/api/v1/trips/a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"vehicle": "https://platform.vin.li/api/v1/vehicles/0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"locations": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/locations?since=1440012315951&until=1440012928875",
"messages": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/messages?since=1440012315951&until=1440012928875",
"events": "https://events.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/events?since=1440012315951&until=1440012928875"
}
}
]
},
"meta": {
"pagination": {
"remaining": 1,
"until": "2015-06-19T23:59:59.000Z",
"since": "1970-01-01T00:00:00.000Z",
"limit": 20,
"sortDir": "desc",
"links": {
"prior": "https://trips-dev.vin.li/api/v1/vehicles/0c785aa0-1a48-4cc6-9f5c-028350dd907d/trips?until=1434129972999"
}
}
}
Get Details of a Trip¶
For each trip, more detailed information regarding overall trip statistics is available here. This includes start and stop location as well as a few other statistical information which may be of interest. These items include:
- averageLoad - average engine load (in percent) of the trip
- averageMovingSpeed - average speed while the vehicle was in motion (eliminates times when the vehicle had a speed of 0)
- averageSpeed - average speed (in kph) of the trip
- distance - total distance traveled (in meters) by the vehicle during this Trip
- distanceByGPS - total distance traveled (in meters) according to GPS. This is more accurate for longer trips, but for shorter trips, it may be inaccurate due to the time to get a fix at the start of a trip.
- distanceByVSS - total distance traveled (in meters) according to the speed of the vehicle. This tends to be more accurate over shorter time periods.
- duration - time (in milliseconds) between the start and end of this trip
- fuelConsumed - estimated amount of fuel (in liters) consumed during this trip
- fuelEconomy - estimated fuel economy (in miles per gallon) during this trip
- hardAccelCount - the number of times the Vehicle experienced a hard acceleration during this trip
- hardBrakeCount - the number of times the Vehicle experienced a hard stop during this trip
- maxSpeed - the maximum speed (in kph) reported for the Vehicle during the Trip
- stdDevMovingSpeed - the standard deviation of the speed while the vehicle was in motion
- stopCount - the number of times the Vehicle came to a stop
All of the detailed information listed in the above verbiage is available via the get trips by device or get trips by vehicle.
Request¶
GET https://trips.vin.li/api/v1/trips/a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"trip": {
"id": "a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"start": "2015-08-19T19:25:15.951Z",
"stop": "2015-08-19T19:35:28.875Z",
"status": "completed",
"vehicleId": "0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"deviceId": "fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"startPoint": {
"type": "Point",
"coordinates": [
-96.789791,
32.780046
]
},
"stopPoint": {
"type": "Point",
"coordinates": [
-96.791057,
32.780671
]
},
"preview": "ijagEdgwmQtC}B`@Q^w@\\U?ICCBA@BFGBKFIB@OLBCm@cBa@u@W[Uo@c@i@Oq@]_@MCw@z@W?F\\?Fd@c@t@a@f@Td@h@b@n@`@v@`@`@b@n@@?CCEFJv@^lATjAHpA@hAH|@Tz@RvAJd@E^U\\eBbCi@l@WTKl@De@?L@AKPy@z@i@b@Yl@u@jAAPU?sAJmADM[g@aCAgCGIEDJm@h@Q`@ICDGA]kAK}@Yy@Bs@Ve@V[f@M^PVb@Ah@CNSXSGAKBGFD",
"stats": {
"averageLoad": 42.6683,
"averageMovingSpeed": 23.1505,
"averageSpeed": 15.4892,
"distance": 2125.35,
"distanceByGPS": 2051.44,
"distanceByVSS": 2125.35,
"duration": 612924,
"fuelConsumed": 0.358368,
"fuelEconomy": 15.277,
"hardAccelCount": null,
"hardBrakeCount": null,
"locationCount": 160,
"maxSpeed": 47,
"messageCount": 182,
"stdDevMovingSpeed": 11.0187,
"stopCount": 8
},
"links": {
"self": "https://trips.vin.li/api/v1/trips/a51a3c87-baa7-4e5d-98e6-4f9588d7c2e1",
"device": "https://platform.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58",
"vehicle": "https://platform.vin.li/api/v1/vehicles/0c785aa0-1a48-4cc6-9f5c-028350dd907d",
"locations": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/locations?since=1440012315951&until=1440012928875",
"messages": "https://telemetry.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/messages?since=1440012315951&until=1440012928875",
"events": "https://events.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/events?since=1440012315951&until=1440012928875"
}
}
}
Behavioral API¶
Report Cards for a Device¶
Returns a Report Card based on historical data for a specified period. In some cases, not enough information was gathered to generate a Report Card. In these cases, the grades will be reported as “I” (for “Incomplete” to keep the school report card metaphore going).
Request¶
GET https://behavior.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"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/b9e58eb4-0743-45e9-b9c6-86500f5412bb",
"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": 34,
"until": "2015-08-13T22:20:59.330Z",
"since": "1970-01-01T00:00:00.000Z",
"limit": 20,
"sortDir": "desc",
"links": {
"prior": "https://behavioral-dev.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards?until=1439418498459"
}
}
}
}
Lifetime Report Card for a Device¶
Returns a Report Card based on all historical data available for a given Device.
Request¶
GET https://behavior.vin.li/api/v1/devices/602c6490-d7a3-11e3-9c1a-0800200c9a66/report_cards/overall
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"reportCard": {
"overallGrade": "A"
}
}
Report Card for a Trip¶
The Trip-specific Report Card contains the same data as the Long-Term and Lifetime Report Card but is specific for a particular Trip.
In some cases, the Trip is too short to generate the data necessary for the Report Card analysis to be run. In these cases, the grades will be reported as “I”.
Request¶
GET https://behavior.vin.li/api/v1/trips/b9e58eb4-0743-45e9-b9c6-86500f5412bb/report_card
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"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": "I",
"links": {
"self": "https://behavioral.vin.li/api/v1/report_cards/549d628c-48dc-412d-8087-44a9f82f187e",
"trip": "https://trips.vin.li/api/v1/trips/b9e58eb4-0743-45e9-b9c6-86500f5412bb",
"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"
}
}
]
}
Safety API¶
Get a list of Collisions for a Device¶
Returns a list of registered Collisions for a given device.
Request¶
GET https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"collisions" : [
{
"id" : "561f0fa0-3231-11e4-8c21-0800200c9a66",
"timestamp" : "2015-07-05T22:16:18+00:00",
"location" : {
"latitude" : 32.766392,
"longitude" : -96.917009
},
"links" : {
"self" : "https://safety.vin.li/api/v1/collisions/561f0fa0-3231-11e4-8c21-0800200c9a66"
}
},
...
],
"meta" : {
"pagination" : {
"total" : 22,
"offset" : 0,
"limit" : 20,
"links" : {
"first" : "https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions?offset=0&limit=20",
"last" : "https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions?offset=20&limit=20",
"next" : "https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions?offset=20&limit=20"
}
}
}
}
Get a list of Collisions for a Vehicle¶
Returns a list of registered Collisions for a given Vehicle.
Request¶
GET https://safety.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755/collisions
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"collisions" : [
{
"id" : "561f0fa0-3231-11e4-8c21-0800200c9a66",
"timestamp" : "2015-07-05T22:16:18+00:00",
"location" : {
"latitude" : 32.766392,
"longitude" : -96.917009
},
"links" : {
"self" : "https://safety.vin.li/api/v1/collisions/561f0fa0-3231-11e4-8c21-0800200c9a66"
}
},
...
],
"meta" : {
"pagination" : {
"total" : 22,
"offset" : 0,
"limit" : 20,
"links" : {
"first" : "https://safety.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755/collisions?offset=0&limit=20",
"last" : "https://safety.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755/collisions?offset=20&limit=20",
"next" : "https://safety.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755/collisions?offset=20&limit=20"
}
}
}
}
Get a specific Collision¶
Returns a list of registered Collisions for a given Vehicle.
Request¶
GET https://safety.vin.li/api/v1/collisions/e43ff87d-bb58-42da-998e-d7f10a3f7a64
Accept: application/json
Response¶
HTTP/1.1 200 OK
Content-Type: application/json
{
"collision" : {
"id" : "e43ff87d-bb58-42da-998e-d7f10a3f7a64",
"timestamp" : "2015-07-05T22:16:18+00:00",
"location" : {
"latitude" : 32.766392,
"longitude" : -96.917009
},
"links" : {
"self" : "https://safety.vin.li/api/v1/collisions/e43ff87d-bb58-42da-998e-d7f10a3f7a64"
}
}
}