Vinli Services Documentation

Overview

Vinli is a platform for easily and quickly building connected car apps. Apps get vehicle data through Vinli services.

Tier 1, raw data services:

  • Platform Service manages devices, gets vehicle information, and monitors transactions.
  • Telemetry Service delivers time-series vehicle data.
  • Event Service delivers vehicle events and offers powerful, rule-based event notifications.
  • Diagnostic Service reveals the malfunction state of the vehicle and provides diagnostic trouble codes.
  • Distance Service estimates the car odometer reading at a point in time and milage travelled in a time interval.

Tier 2, structured data services:

  • Trip Service organizes and summarizes telemetry by vehicle ignition and shutdown.
  • Behavioral Service categorizes driver risk based on behavior, vehicle conditions, and geographical travel patterns. It assigns a risk score.
  • Safety Service provides history and telemetry details of collisions.
  • Rule Service creates event subscriptions based on vehicle state or geofences.

Testing and Prototyping

You can quickly prototype an app using Virtual Vinli.

Contents

The Vinli Platform

Vinli Platform service:

  • authenticates your application, Vinli device and
  • configures pagination

Authentication using OAUTH 2 is mandatory for all Vinli apps. Apps must authenticate themselves and user actions to use Vinli services.

Vinli paginates data using:

  • resource lists for static resources, or
  • streams for rapidly changing data

Pagination can alter the format of dates and times. It’s an important topic for apps that rely on telemetry data.

Authentication

Apps must authenticate through Vinli Platform services. When you register an app at dev.vin.li, the Vinli Platform assigns a unique App ID and App Secret. Your app will need both, to authenticate with Vinli services.

All API calls must use HTTP/SSL. Vinli will reject all plain HTTP calls at the socket level.

Application Authentication

Each request must include the App ID and App Secret in the Authorization header of the request. This takes the form of a standard BasicAuth header where the App ID is the username and the App Secret is the password. For example, an Application with the following credentials:

  • App ID: c87d5be0-2e69-11e4-8c21-0800200c9a66
  • App Secret: HKLFFoSILb8VHFJD

could request a list of all of its Devices using CURL with

curl -u c87d5be0-2e69-11e4-8c21-0800200c9a66:HKLFFoSILb8VHFJD https://platform.vin.li/api/v1/devices

and CURL will take care of setting the Authorization header. Almost all HTTP libraries can handle BasicAuth for you, as long as you have a username and password.

If you must implement BasicAuth yourself, follow the steps below to generate the header value:

  1. Combine the App ID and App Secret using a colon. Ex: c87d5be0-2e69-11e4-8c21-0800200c9a66:HKLFFoSILb8VHFJD
  2. Encode the string as Base64 (specifically the RFC2045-MIME variant).
  3. Prepend the string “Basic ” (note the space after the word ‘Basic’) to the the encoded string.

For the example above, the Authorization header would be sent as:

Authorization: Basic Yzg3ZDViZTAtMmU2OS0xMWU0LThjMjEtMDgwMDIwMGM5YTY2OkhLTEZGb1NJTGI4VkhGSkQ=

Important: the App Secret should be kept safe and rotated often. You can reset the App Secret from the App Management page of the Developer Portal at dev.vin.li.

User Action Authentication

Vinli services require user actions to authernticate with OAuth 2. Developers must register their apps for each platform they would like to support. at dev.vin.li.

In general, there are two types of OAuth 2 clients, those that expect response tokens and those that expect response codes.

Vinli supports two OAuth 2 flows:

  • Implicit Grant Flow is used for clients that cannot secure their App Secret. For example, web clients and mobile apps.
  • Authorization Code Flow is used for clients that can be secured against leaking their App Secret. For example, server clients or clients that require long-lived access.

Implicit Grant Flow clients are directly granted a token by the authentication service in exchange for their ID, redirect URI, and the user’s approval.

Authorization Code clients use a user-facing component to obtain a code from the authentication service in exchange for their ID, redirect URI, and the user’s approval. The user-facing component then hands the code to the secure client. The secure client can then obtain an access token from the authentication service in exchange for its ID, secret, and the authentication code.

To initiate the authentication flow, the client directs the user to:

https://auth.vin.li/oauth/authorization/new?client_id={clientId}&redirect_uri={redirectUri}&response_type={desiredResponseType}

After user authentication and app approval, the app should redirect to the provided redirect URI, which must match the redirect URI registered for the client. For the access token, the requested data will be in the fragment (after the #) portion of the URI. For the authentication code, the requested data will be in the query (after the ?). Error will be returned in the body.

Developer Device Authentication

There is no connection between a MyVinli account and a Dev Portal account, even if they share an email address.

However, it can be useful to add a device to your application, before you have a full OAuth flow implemented. After adding a device, you can inspect data from a device or experiment with the Vinli Platform API.

Follow the procedure below to add a device to your app:

  1. Create a MyVinli account and follow the steps to add and name your device.
  2. Create a Vinli Developer account.
  3. From the Vinli Developer Portal, create an OAuth client. The Client Type should be set to Web. For the purposes of this procedure, the Redirect URI does not have to point to an existing URL.
  4. Download the script files and follow the steps in this gist. Use your MyVinli credentials, the ID and Redirect URI of the Oauth client that you created in step 3.

After adding the device, you can view the device data in the Dev Portal. You can also use the Bearer token, returned by step 4, to access device data using the HTTP API.

Dates and Times

Before using Vinli services, it’s worth spending some time to discuss date and time formatting.

Submitting Dates

As part of URLs, dates can be submitted in two ways: ISO8601 formatted or Unix Time. Both are accepted by the platform APIs and will be converted equally. As an example, the following are all equivalent as far as the Vinli platform is concerned and will retrieve the same set of snapshots (those occuring after 12:32pm CDT on September 7th, 2014):

ISO 8601
  • 2014-09-07T17:32:57.893Z -> https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?since=2014-09-07T17%3A32%3A57.893Z
  • 2014-09-07T17:32:57.893+00:00 -> https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?since=2014-09-07T17%3A32%3A57.893%2B00%3A00
  • 2014-09-07T12:32:57.893-05:00 -> https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?since=2014-09-07T12%3A32%3A57.893-05%3A00
Unix Time
  • 1410111177893 -> https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?since=1410111177893

There is obviously a lot that could be discussed regarding the benefits and drawbacks of each style of date. In general, Unix Time is completely unambiguous, is smaller in footprint (for URLs and storage), does not need to be URL encoded, and is available easily in all major lanuganges; however, ISO 8601 is much easier to read and debug as a human.

In either case, Vinli will handle the dates without issue.

Receiving Dates

Where possible, Vinli Platform’s APIs will return dates as ISO 8601 formatted Strings. This makes working with the API with debugging tools much easier as the dates will already be easily human-readable. All major date libraries are able to parse ISO 8601 natively without much fuss.

Pagination metadata that uses the “Stream Pagination”, will generally return URLs with Unix Time query parameters. As stated above, this avoids any issues with URL encoding and provides for slightly smaller URLs.

Platform Services

Platform Services allow:

  • administration of devices
  • access to vehicle information, including connected devices
  • access to application transaction history

The Vinli device is your app’s link to vehicles and drivers. Platform Service helps you keep track of those devices and vehicles.

Apps can access their transaction history. This gives apps a kind of persistent memory of actions taken on the driver’s behalf. Apps can use transaction history in many ways:

  • see recent transactions
  • an administrative log
  • to take action on recent administrative events

When device and vehicle data are combined with transaction history, apps can:

  • better personalize the app experience
  • give hints or tips to users
  • help drivers understand app configuration options

Device Service

The root element in all interaction with the Vinli platform is the Device. Each Vinli device has an associated Device ID by which it is referred to within the platform. However, before your application can access any data or perform any actions on a Device, it must be authorized by the owner of the device.

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": "ab4c96ec-4052-4002-9576-bef5d8eb8517",
      "name": "Vrrrooom",
      "chipId": "VV89CCF24172",
      "createdAt": "2016-06-07T16:50:38.148Z",
      "icon": "https://vinli-public.s3.amazonaws.com/auth-service/prod/efd48eaf-4dfb-2a1e-8207-0e1037638532/cirpxptlm00000fbulfuxzxxj",
      "links": {
        "self": "https://platform.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517",
        "vehicles": "https://platform.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/vehicles",
        "latestVehicle": "https://platform.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/vehicles/_latest",
        "rules": "https://rules.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/rules",
        "events": "https://events.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/events",
        "subscriptions": "https://events.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/subscriptions",
        "trips": "https://trips.vin.li/api/v1/devices/ab4c96ec-4052-4002-9576-bef5d8eb8517/trips"
      }
    },
    {
      "id": "2a73c50d-1121-4913-94e6-770f22a5e979",
      "name": "Virtual Vinli Hot Rod",
      "chipId": "VV2A406C5147",
      "createdAt": "2016-09-14T09:02:20.998Z",
      "icon": "https://vinli-public.s3.amazonaws.com/auth-service/prod/eed49eaf-4dfb-2a1e-8207-0e1037638532/cirpxptlm00000fbulguozxzj",
      "links": {
        "self": "https://platform.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979",
        "vehicles": "https://platform.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979/vehicles",
        "latestVehicle": "https://platform.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979/vehicles/_latest",
        "rules": "https://rules.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979/rules",
        "events": "https://events.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979/events",
        "subscriptions": "https://events.vin.li/api/v1/devices/2a73c50d-1121-4913-94e6-770f22a5e979/subscriptions",
        "trips": "https://trips.vin.li/api/v1/devices/1a73c50d-1171-4915-94e8-170a21a5e978/trips"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 20,
      "offset": 0,
      "links": {
        "first": "https://platform.vin.li/api/v1/devices?limit=20&offset=0",
        "last": "https://platform.vin.li/api/v1/devices?limit=20&offset=0"
      }
    }
  }
}
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",
    "name": "Mystery Machine",
    "chipId": "VV55C6887CBA",
    "createdAt": "2016-04-07T14:56:18.306Z",
    "icon": "https://vinli-public.s3.amazonaws.com/auth-service/prod/3de63923-c9bc-4ca4-b1f1-50daed3ab76c/cimqf7cnm01020ecwvyx8ae45",
    "links": {
      "self": "https://platform.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66",
      "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",
      "rules": "https://rules.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/rules",
      "events": "https://events.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/events",
      "subscriptions": "https://events.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/subscriptions",
      "trips": "https://trips.vin.li/api/v1/devices/821374c0-d6d8-11e3-9c1a-0800200c9a66/trips"
    }
  }
}
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",
      "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 Service

Vinli keeps track of which vehicle a device is or has been plugged into and provides detailed information regarding the specifics about the vehicle. This gives your application the chance to better personlize the experience of a user as well as the information necessary to classify users and their data by vehicle. You are only allowed to see vehicles that are associated with a device to which you’re application has access.

Vehicle-device assocation is time-based. A device that is plugged into one vehicle will be associated with that vehicle until it is plugged into a differnt vehicle. Vinli keeps track of this history for you. In the case of a device that is shared between multiple vehicles, the same vehicle will appear multiple times in the history.

Note that when a vehicle is first added to the system (when a Vinli device is plugged into a specific vehicle for the first time), only the VIN number is available. At some point in time after this, Vinli will update the vehicle information with Year, Make, Model, and Trim in addition to even more detailed information (available through the Vehicle’s “self” link).

List All of a Device’s Vehicles

Returns the vehicles associated with the given device in time series 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",
      "vin": "2B4GP44R6WR942762",
      "make": "Honda",
      "model": "CR-V",
      "year": "2010",
      "trim": "EX-L 4dr SUV w/Navigation (2.4L 4cyl 5A)",
      "data": {
        "engine": {
          "name": "Engine",
          "equipmentType": "ENGINE",
          "availability": "STANDARD",
          "compressionRatio": 10.5,
          "cylinder": 4,
          "size": 2.4,
          "displacement": 2354,
          "configuration": "inline",
          "fuelType": "regular unleaded",
          "horsepower": 180,
          "torque": 161,
          "totalValves": 16,
          "type": "gas",
          "code": "4INAG2.4",
          "compressorType": "NA",
          "rpm": {
            "horsepower": 6800,
            "torque": 4400
          },
          "valve": {
            "timing": "variable valve timing",
            "gear": "double overhead camshaft"
          }
        },
        "engineDisplacement": 2354,
        "transmission": {
          "name": "5A",
          "equipmentType": "TRANSMISSION",
          "availability": "STANDARD",
          "transmissionType": "AUTOMATIC",
          "numberOfSpeeds": "5"
        },
        "manufacturer": null,
        "categories": {
          "market": "Crossover",
          "EPAClass": "Sport Utility Vehicles",
          "vehicleSize": "Compact",
          "crossover": "Car",
          "primaryBodyType": "SUV",
          "vehicleStyle": "4dr SUV",
          "vehicleType": "SUV"
        },
        "epaMpg": {
          "highway": "28",
          "city": "21"
        },
        "drive": "front wheel drive",
        "numDoors": "4"
      },
      "createdAt": "2016-06-08T20:56:33.033Z",
      "links": {
        "self": "https://platform.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66",
        "trips": "https://trips.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/trips",
        "codes": "https://diagnostic.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/codes",
        "collisions": "https://safety.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/collisions"
      },
      "lastStartup": "2016-12-19T14:12:19.476Z"
    },
    {
      "id" : "67e1e940-d6da-11e3-9c1a-0800200c9a66",
      "year" : "2007",
      "make" : "Toyota",
      "model" : "Camry",
      "trim" : "SE V6",
      "vin" : "2B4GP44R6WR942762",
      "data" : {
        "engine": {
          "id": "200373059",
          "name": "Engine",
          "equipmentType": "ENGINE",
          "availability": "STANDARD",
          "compressionRatio": 10.6,
          "cylinder": 4,
          "size": 1.8,
          "displacement": 1798,
          "configuration": "inline",
          "fuelType": "regular unleaded",
          "horsepower": 140,
          "torque": 128,
          "totalValves": 16,
          "type": "gas",
          "code": "4INAG1.8",
          "compressorType": "NA",
          "rpm": {
            "horsepower": 6500,
            "torque": 4300
          },
          "valve": {
            "timing": "variable valve timing",
            "gear": "single overhead camshaft"
          }
        },
        "engineDisplacement": 1798,
        "transmission": null,
        "manufacturer": null,
        "categories": {
          "market": "N/A",
          "EPAClass": "Compact Cars",
          "vehicleSize": "Compact",
          "primaryBodyType": "Car",
          "vehicleStyle": "Sedan",
          "vehicleType": "Car"
        },
        "epaMpg": {
          "highway": "39",
          "city": "28"
        },
        "drive": "front wheel drive",
        "numDoors": "4"
      },
      "createdAt": "2016-08-08T21:12:18.692Z",
      "links": {
        "self": "https://platform-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66",
        "trips": "https://trips-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/trips",
        "codes": "https://diagnostic-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/codes",
        "collisions": "https://safety-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/collisions"
      },
      "lastStartup": "2016-08-08T21:12:16.828Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 20,
      "offset": 0,
      "links": {
        "first": "https://platform.vin.li/api/v1/devices/60599e46-e221-4df7-8bc6-077c9538141d/vehicles?limit=20&offset=0",
        "last": "https://platform.vin.li/api/v1/devices/60599e46-e221-4df7-8bc6-077c9538141d/vehicles?limit=20&offset=0"
      }
    }
  }
}
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" : {
      "engine": {
        "id": "200373059",
        "name": "Engine",
        "equipmentType": "ENGINE",
        "availability": "STANDARD",
        "compressionRatio": 10.6,
        "cylinder": 4,
        "size": 1.8,
        "displacement": 1798,
        "configuration": "inline",
        "fuelType": "regular unleaded",
        "horsepower": 140,
        "torque": 128,
        "totalValves": 16,
        "type": "gas",
        "code": "4INAG1.8",
        "compressorType": "NA",
        "rpm": {
          "horsepower": 6500,
          "torque": 4300
        },
        "valve": {
          "timing": "variable valve timing",
          "gear": "single overhead camshaft"
        }
      },
      "engineDisplacement": 1798,
      "transmission": null,
      "manufacturer": null,
      "categories": {
        "market": "N/A",
        "EPAClass": "Compact Cars",
        "vehicleSize": "Compact",
        "primaryBodyType": "Car",
        "vehicleStyle": "Sedan",
        "vehicleType": "Car"
      },
      "epaMpg": {
        "highway": "39",
        "city": "28"
      },
      "drive": "front wheel drive",
      "numDoors": "4"
    },
    "createdAt": "2016-08-08T21:12:18.692Z",
    "links": {
      "self": "https://platform-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66",
      "trips": "https://trips-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/trips",
      "codes": "https://diagnostic-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/codes",
      "collisions": "https://safety-dev.vin.li/api/v1/vehicles/67e1e940-d6da-11e3-9c1a-0800200c9a66/collisions"
    },
    "lastStartup": "2016-08-08T21:12:16.828Z"
  }
}

Transaction Service

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": {
    "stats": {
      "periodTotal": 1058,
      "serviceUsage": {
        "vinli-dummy-service": 226,
        "vinli-platform-service": 222,
        "vinli-event-service": 219,
        "vinli-telemetry-service": 124,
        "vinli-distance-service": 69,
        "vinli-behavioral-service": 53,
        "vinli-rule-service": 53,
        "vinli-trip-service": 48,
        "vinli-diagnostic-service": 31,
        "vinli-safety-service": 13
      },
      "allTimeTotal": 1058
    },
    "pagination": {
      "remaining": 1038,
      "until": "2016-12-19T19:48:01.135Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 20,
      "sortDir": "desc",
      "links": {
        "prior": "https://platform.vin.li/api/v1/transactions?until=1481558446263"
      }
    }
  }
}

Telemetry Services

Telemetry Services provide time-series data from vehicle parameters and location. This history is available in three formats:

  • messages format provides time-series of the raw, unfiltered messages from a device
  • locations format returns time-series of locations with corresponding vehicle parameters returned as valid GeoJSON
  • telemetry snapshots deliver time-series history of one or more vehicle parameters

All of these data formats are provided using stream pagination.

The reported format of each parameter can be different depending on the type of vehicle or the vehicle’s condition.

Some parameters change often, and others not at all. For example, Telemetry Service sends RPM, vehicle speed, etc. as often as possible, location with every message when available. However, Fuel Type or O2 Sensor Locations will never change.

In any case, all parameters that are provided by a vehicle are reported at least once every minute or so after startup.

Telemetry Messages

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": "c5c55c92-59ae-440d-881e-24f6b287ac32",
      "timestamp": "2016-12-19T14:21:45.846Z",
      "data": {
        "location": {
          "type": "Point",
          "coordinates": [
            -96.790123,
            32.782034
          ]
        },
        "accel": {
          "maxZ": -5.707806,
          "maxX": -0.344767,
          "maxY": -7.240103,
          "minX": -0.651226,
          "minY": -7.27841,
          "minZ": -7.316718
        },
        "designOBDRequirements": "OBD-II as defined by the CARB",
        "rpm": 940,
        "vehicleSpeed": 16,
        "intakeManifoldPressure": 32,
        "calculatedLoadValue": 29.019607843137255,
        "massAirFlow": 4.49
      },
      "links": {
        "self": "https://telemetry.vin.li/api/v1/messages/c5c55c92-59ae-440d-881e-24f6b287ac32?deviceId=27a2ac50-d7bd-11e3-9c1a-0800200c9a66"
      }
    },
    {
      "id": "8bc21558-0ec5-4a77-b82e-e6a23c95675c",
      "timestamp": "2016-12-19T14:21:45.000Z",
      "data": {
        "location": {
          "type": "Point",
          "coordinates": [
            -96.790127,
            32.782054
          ]
        },
        "accel": {
          "maxZ": -5.286424,
          "maxX": -0.651226,
          "maxY": -7.393332,
          "minX": -1.072608,
          "minY": -7.43164,
          "minZ": -7.661484
        },
        "rpm": 1027,
        "oxygenSensorVoltage1b": 0.69,
        "shortTermFuelTrim1b": 0,
        "vehicleSpeed": 15,
        "intakeManifoldPressure": 39,
        "calculatedLoadValue": 34.509803921568626,
        "massAirFlow": 5.76
      },
      "links": {
        "self": "https://telemetry.vin.li/api/v1/messages/8bc21558-0ec5-4a77-b82e-e6a23c95675c?deviceId=27a2ac50-d7bd-11e3-9c1a-0800200c9a66"
      }
    },
    {
      "id": "fa23ac3c-9987-46ee-8969-bedaabd7819f",
      "timestamp": "2016-12-19T14:21:44.069Z",
      "data": {
        "location": {
          "type": "Point",
          "coordinates": [
            -96.790113,
            32.782085
          ]
        },
        "accel": {
          "maxZ": -6.24411,
          "maxX": -0.727841,
          "maxY": -6.971951,
          "minX": -1.608912,
          "minY": -7.27841,
          "minZ": -7.316718
        },
        "rpm": 902,
        "oxygenSensorLocations": [
          "Bank 1 Sensor 1",
          "Bank 1 Sensor 2"
        ],
        "vehicleSpeed": 15,
        "intakeManifoldPressure": 40
      },
      "links": {
        "self": "https://telemetry.vin.li/api/v1/messages/fa23ac3c-9987-46ee-8969-bedaabd7819f?deviceId=27a2ac50-d7bd-11e3-9c1a-0800200c9a66"
      }
    },
    {
      "id": "3297440a-b839-41a8-9559-75e308a6e384",
      "timestamp": "2016-12-19T14:21:43.210Z",
      "data": {
        "location": {
          "type": "Point",
          "coordinates": [
            -96.790111,
            32.782127
          ]
        },
        "accel": {
          "maxZ": -6.703799,
          "maxX": -0.612919,
          "maxY": -6.397339,
          "minX": -0.612919,
          "minY": -7.58487,
          "minZ": -6.742106
        },
        "calculatedLoadValue": 36.86274509803921,
        "massAirFlow": 6.1,
        "rpm": 888,
        "absoluteThrottleSensorPosition": 13.72549019607843
      },
      "links": {
        "self": "https://telemetry.vin.li/api/v1/messages/3297440a-b839-41a8-9559-75e308a6e384?deviceId=27a2ac50-d7bd-11e3-9c1a-0800200c9a66"
      }
    },
  ],
  "meta": {
    "pagination": {
      "remaining": 709,
      "until": "2016-12-19T19:53:39.244Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 4,
      "sortDir": "desc",
      "links": {
        "prior": "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/messages?limit=5&until=1461943861926"
      }
    }
  }
}
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 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
{
  "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": 469,
      "until": "2016-12-20T00:02:36.644Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 3,
      "sortDir": "desc",
      "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=vehicleSpeed,rpm
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": [
        {
        "id": "090442e2-6c04-3473-bf15-549622329c79",
        "timestamp": "2016-12-19T23:05:43.074Z",
        "data": {
            "vehicleSpeed": 12,
            "rpm": 850
        },
        "links": {
            "self": "https://telemetry.vin.li/api/v1/messages/090442e2-6c04-3473-bf15-549622329c79"
            }
        },
        {
        "id": "b8664969-dfba-4536-b610-1cdc2657d8b2",
        "timestamp": "2016-12-19T23:05:42.198Z",
        "data": {
            "rpm": 1805
        },
        "links": {
            "self": "https://telemetry.vin.li/api/v1/messages/b8664969-dfba-4536-b610-1cdc2657d8b2"
            }
        },
        {
        "id": "89c4d874-cde5-4e7c-b7b4-59ce18d892d3",
        "timestamp": "2016-12-19T23:05:41.268Z",
        "data": {
            "vehicleSpeed": 19,
            "rpm": 1768
        },
        "links": {
            "self": "https://telemetry.vin.li/api/v1/messages/89c4d874-cde5-4e7c-b7b4-59ce18d892d3"
            }
        }
    ],
    "meta": {
        "pagination": {
        "remaining": 797812,
        "until": "2016-12-20T00:11:10.993Z",
        "since": "1970-01-01T00:00:00.000Z",
        "limit": 3,
        "sortDir": "desc",
        "links": {
            "prior": "https://telemetry.vin.li/api/v1/devices/27a2ac50-d7bd-11e3-9c1a-0800200c9a66/snapshots?fields=vehicleSpeed,rpm"
            }
        }
    }
}

Supported PIDs

Vinli supports most legislatively required, Mode 1 PIDs within the OBDII protocol. Additionally, we’re able to read the VIN. For a complete and up-to-date list of supported PIDs, please visit http://dev.vin.li/parameters.json

If you have a specific question about suppoted PIDs, or are interested in obtaining data points that aren’t shown in the parameters.json file, please email us at dev@vin.li

Event Services

The set of tools provided by Vinli’s Event Services allows an application to create and manage complex sets of Rules that are evaluated on particular devices or groups of devices. These Rules are constructed using the parameters provided by the Vinli device. More information about these parameters can be found in the “Parameters” section above, but it’s important to note that only those parameters with a decimal dataType are usable in Rules.

As data is streamed from the Vinli device to the platform, each snapshot is evaluated by the Event Service to see if the new information causes the device to leave or enter the boundaries of a given rule. This can get a bit complicated, especially as the rules your application need grow. The important thing to remember is that a Rule represents a continuity of states that the vehicle is either inside of (covered) or outside of (not covered).

Overview

The API routes provided by the Event Service work in concert to provide both access to the historical events for a Device or Vehicle as well as web-hooks for your App to receive immediate notification when an event occurs.

The normal life-cycle of working with Event Service is:

  • Create a Subscription for a particular event type for a device or vehicle
  • That event occurs for that device/vehicle
  • An event is created
  • Event Service looks for all Subscriptions for which this Event qualifies
  • A Notification is created that contains all the relevant information
  • The Notification is POSTed to the URL listed in the Subscription
  • Links within the Notification allow the App to explore the related information directly
Event Types

There are several types of events that the platform will track on a device-by-device basis. These include:

  • startup
  • shutdown
  • rule-enter
  • rule-leave
  • dtc-on
  • dtc-off
  • collision
  • trip-started
  • trip-orphaned
  • trip-stopped
  • trip-completed
  • distance-trigger
Objects

Almost all events occur in the context of a higher-level object. For example, startup and shutdown events occur in relation to a given Vehicle, rule-enter and rule-leave events occur in relation to a given Rule. This information is available as part of the event object property. Additionally, subscriptions can specifically reference a given object. For example, a subscription to startup events can optionally reference a particular Vehicle; in this way, an App will only be notified of startups where the Device is attached to a particular Vehicle.

NOTE: Subscriptions for event types rule-enter, rule-leave, or rule-* must reference a single Rule. When creating the subscription, the Rule is checked to ensure that it belongs to this particular device.

Events

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
  • vehicleId - ID of the vehicle
  • 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 eventType
  • 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. Defaults to 20.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "events": [
    {
      "id": "5dd7722c-58e2-4f66-9636-e57dd829abbe",
      "timestamp": "2016-12-20T17:44:09.187Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "trip-completed",
      "object": {
        "id": "1b8b9447-428c-4c0d-631d-1bc27b401c15",
        "type": "trip"
      },
      "meta": {
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f"
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/5dd7722c-58e2-4f66-9636-e57dd829abbe",
        "notifications": "https://events.vin.li/api/v1/events/5dd7722c-58e2-4f66-9636-e57dd829abbe/notifications"
      }
    },
    {
      "id": "0e9a17ff-6f81-436f-9686-2f517928fe65",
      "timestamp": "2016-12-20T17:44:04.587Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "trip-stopped",
      "object": {
        "id": "1b8b9447-428c-4c0d-631d-1bc27b401c15",
        "type": "trip"
      },
      "meta": {
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f"
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/0e9a17ff-6f81-436f-9686-2f517928fe65",
        "notifications": "https://events.vin.li/api/v1/events/0e9a17ff-6f81-436f-9686-2f517928fe65/notifications"
      }
    },
    {
      "id": "49f0f996-ace4-4fb2-bcd1-be1ae4979866",
      "timestamp": "2016-12-20T17:44:04.587Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "shutdown",
      "object": {
        "id": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "type": "vehicle"
      },
      "meta": null,
      "links": {
        "self": "https://events.vin.li/api/v1/events/49f0f996-ace4-4fb2-bcd1-be1ae4979866",
        "notifications": "https://events.vin.li/api/v1/events/49f0f996-ace4-4fb2-bcd1-be1ae4979866/notifications"
      }
    },
    {
      "id": "6bcad159-a0dc-4962-97bb-52195b02abd7",
      "timestamp": "2016-12-14T22:40:28.064Z",
      "deviceId": "eb4f66ec-4050-4052-9559-baf5d8eb8511",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "dtc-on",
      "object": {
        "id": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "type": "vehicle"
      },
      "meta": {
        "code": "313bc7d7-1fc6-491f-9e02-c3d02e64994c"
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/6bcad159-a0dc-4962-97bb-52195b02abd7",
        "notifications": "https://events.vin.li/api/v1/events/6bcad159-a0dc-4962-97bb-52195b02abd7/notifications"
      }
    },
    {
      "id": "3aacec4e-e478-31ec-7008-0aad4093c328",
      "timestamp": "2016-12-20T17:42:33.131Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "rule-enter",
      "object": {
        "id": "b40439e2-8c9b-4684-a2c9-daaa76d9a13c",
        "type": "rule"
      },
      "meta": {
        "direction": "enter",
        "firstEval": false,
        "rule": {
          "id": "b40439e2-8c9b-4684-a2c9-daaa76d9a13c",
          "name": "got to work",
          "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
          "object": {
            "id": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
            "type": "device"
          },
          "boundaries": [
            {
              "id": "652c3b9c-aace-420d-aa29-0aa518659317",
              "type": "polygon",
              "coordinates": [
                [
                  [
                    -96.7904305458069,
                    32.7828150725714
                  ],
                  [
                    -96.7917609214783,
                    32.782544470838
                  ],
                  [
                    -96.7914605140686,
                    32.7811914498245
                  ],
                  [
                    -96.7906773090363,
                    32.7810381061449
                  ],
                  [
                    -96.7893040180206,
                    32.7816604994394
                  ],
                  [
                    -96.788467168808,
                    32.782535450766
                  ],
                  [
                    -96.7894649505615,
                    32.7828511527404
                  ],
                  [
                    -96.7903876304626,
                    32.7828150725714
                  ],
                  [
                    -96.7904305458069,
                    32.7828150725714
                  ]
                ]
              ]
            }
          ],
          "evaluated": true,
          "covered": true,
          "createdAt": "2016-12-20T01:15:38.843987+00:00",
          "links": {
            "self": "https://rules.vin.li/api/v1/rules/b40439e2-8c9b-4684-a2c9-daaa76d9a13c",
            "events": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?type=rule-*&objectId=b40439e2-8c9b-4684-a2c9-daaa76d9a13c",
            "subscriptions": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/subscriptions?objectType=rule&objectId=b40439e2-8c9b-4684-a2c9-daaa76d9a13c"
          }
        },
        "message": {
          "id": "edfe24c4-bcd0-4912-b63f-e1581eacf431",
          "timestamp": "2016-12-20T17:42:33.131Z",
          "snapshot": {
            "location": {
              "lat": 32.782804,
              "lon": -96.789367
            },
            "accel": {
              "maxZ": -5.094887,
              "maxX": 0.651226,
              "maxY": -5.899343,
              "minX": 0.268152,
              "minY": -6.014265,
              "minZ": -6.703799
            },
            "rpm": 1280,
            "calculatedLoadValue": 17.254901960784313,
            "designOBDRequirements": "OBD-II as defined by the CARB",
            "vehicleSpeed": 50,
            "intakeManifoldPressure": 23,
            "massAirFlow": 3.9
          }
        }
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/3aacec4e-e478-31ec-7008-0aad4093c328",
        "notifications": "https://events.vin.li/api/v1/events/3aacec4e-e478-31ec-7008-0aad4093c328/notifications"
      }
    },
    {
      "id": "217d0534-bc62-3fc3-9f58-3114fe9bc765",
      "timestamp": "2016-12-20T21:33:05.285Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": null,
      "eventType": "rule-enter",
      "object": {
        "id": "3a18675d-b404-8918-a3d4-15693472ae13",
        "type": "rule"
      },
      "meta": {
        "direction": "enter",
        "firstEval": false,
        "rule": {
          "id": "3a18675d-b404-8918-a3d4-15693472ae13",
          "name": "Speedster!",
          "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
          "object": {
            "id": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
            "type": "device"
          },
          "boundaries": [
            {
              "id": "95c9ea11-17ae-3991-8b2f-d3acb86672f3",
              "type": "parametric",
              "parameter": "vehicleSpeed",
              "min": 65
            }
          ],
          "evaluated": true,
          "covered": true,
          "createdAt": "2016-12-20T21:31:15.359984+00:00",
          "links": {
            "self": "https://rules.vin.li/api/v1/rules/3a18675d-b404-8918-a3d4-15693472ae13",
            "events": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?type=rule-*&objectId=3a18675d-b404-8918-a3d4-15693472ae13",
            "subscriptions": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/subscriptions?objectType=rule&objectId=3a18675d-b404-8918-a3d4-15693472ae13"
          }
        },
        "message": {
          "id": "7a8582b0-d6b4-48a9-9c34-7af932295b4a",
          "timestamp": "2016-12-20T21:33:05.285Z",
          "snapshot": {
            "location": {
              "lat": 32.77653,
              "lon": -96.799442
            },
            "accel": {
              "maxZ": 9.883315,
              "maxX": 2.489982,
              "maxY": -4.252124,
              "minX": -0.995993,
              "minY": -7.929636,
              "minZ": 4.290431
            },
            "calculatedLoadValue": 18.431372549019606,
            "intakeManifoldPressure": 27,
            "rpm": 3320,
            "massAirFlow": 6.64,
            "longTermFuelTrimBank1": -1.5625,
            "vehicleSpeed": 67,
            "shortTermFuelTrimBank2": 0
          }
        }
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/217d0534-bc62-3fc3-9f58-3114fe9bc765",
        "notifications": "https://events.vin.li/api/v1/events/217d0534-bc62-3fc3-9f58-3114fe9bc765/notifications"
      }
    },
    {
      "id": "b066c41a-c243-4a40-af09-8900c0b25e7f",
      "timestamp": "2016-11-27T16:52:57.152Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "38ef2962-7fd2-4319-8389-f9a6b85a7e3f",
      "eventType": "rule-leave",
      "object": {
        "id": "6ad6dcab-4e15-334a-ba3f-5bb9a7ddb7fe",
        "type": "rule"
      },
      "meta": {
        "direction": "leave",
        "firstEval": false,
        "rule": {
          "id": "6ad6dcab-4e15-334a-ba3f-5bb9a7ddb7fe",
          "name": "radius geofence",
          "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
          "object": {
            "id": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
            "type": "device"
          },
          "boundaries": [
            {
              "id": "5714379f-c5f3-4052-ad5d-0aa22032475b",
              "type": "radius",
              "radius": 312.33,
              "lon": -96.7899370193481,
              "lat": 32.8242218079282
            }
          ],
          "evaluated": true,
          "covered": true,
          "createdAt": "2016-07-23T05:41:28.179+00:00",
          "links": {
            "self": "https://rules.vin.li/api/v1/rules/6ad6dcab-4e15-334a-ba3f-5bb9a7ddb7fe",
            "events": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?type=rule-*&objectId=6ad6dcab-4e15-334a-ba3f-5bb9a7ddb7fe",
            "subscriptions": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/subscriptions?objectType=rule&objectId=6ad6dcab-4e15-334a-ba3f-5bb9a7ddb7fe"
          }
        },
        "message": {
          "id": "31104e29-84ec-4775-9a32-d667e6287292",
          "timestamp": "2016-11-27T16:52:57.152Z",
          "snapshot": {
            "location": {
              "lat": 32.823664,
              "lon": -96.793123
            },
            "accel": {
              "maxZ": -5.975958,
              "maxX": 0.612919,
              "maxY": -7.201795,
              "minX": -0.727841,
              "minY": -7.240103,
              "minZ": -8.312711
            },
            "rpm": 1406,
            "intakeManifoldPressure": 37,
            "calculatedLoadValue": 33.333333333333336,
            "massAirFlow": 9.76,
            "vehicleSpeed": 34
          }
        }
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/b066c41a-c243-4a40-af09-8900c0b25e7f",
        "notifications": "https://events.vin.li/api/v1/events/b066c41a-c243-4a40-af09-8900c0b25e7f/notifications"
      }
    },
    {
      "id": "747e3642-b481-4589-a7af-cbb512319d03",
      "timestamp": "2016-12-20T17:35:43.357Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "trip-started",
      "object": {
        "id": "1b8b9447-428c-4c0d-631d-1bc27b401c15",
        "type": "trip"
      },
      "meta": {
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f"
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/747e3642-b481-4589-a7af-cbb512319d03",
        "notifications": "https://events.vin.li/api/v1/events/747e3642-b481-4589-a7af-cbb512319d03/notifications"
      }
    },
    {
      "id": "97baaf93-d7ac-443b-a296-4e6cbb1a1cc7",
      "timestamp": "2016-12-20T17:35:43.357Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "startup",
      "object": {
        "id": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "type": "vehicle"
      },
      "meta": null,
      "links": {
        "self": "https://events.vin.li/api/v1/events/97baaf93-d7ac-443b-a296-4e6cbb1a1cc7",
        "notifications": "https://events.vin.li/api/v1/events/98bbaf93-d7bc-444b-b296-4e6cbb1a1cc8/notifications"
      }
    },
    {
      "id": "b3d2444-78ec-45d8-8073-13421ad2ef96",
      "timestamp": "2016-12-19T13:31:00.491Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "phone-home",
      "object": {
        "id": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "type": "vehicle"
      },
      "meta": null,
      "links": {
        "self": "https://events.vin.li/api/v1/events/b3d2444-78ec-45d8-8073-13421ad2ef96",
        "notifications": "https://events.vin.li/api/v1/events/b3d2444-78ec-45d8-8073-13421ad2ef96/notifications"
      }
    },
  ],
  "meta": {
    "pagination": {
      "remaining": 7993,
      "until": "2016-12-20T21:04:26.443Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 10,
      "sortDir": "desc",
      "links": {
        "prior": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?limit=100&until=1482013267165"
      }
    }
  }
}
Get All Events for a Vehicle
Request
GET https://events.vin.li/api/v1/vehicles/48ef1264-7fd2-4319-8789-g9a6b85b7a8f/events
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "events": [
    {
      "id": "c0c19d22-0f59-4140-9076-c61f61740f76",
      "timestamp": "2016-10-20T17:29:48.753Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "trip-completed",
      "object": {
        "id": "310d9507-deae-437c-a18c-4b7909173939",
        "type": "trip"
      },
      "meta": {
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f"
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/c0c19d22-0f59-4140-9076-c61f61740f76",
        "notifications": "https://events.vin.li/api/v1/events/c0c19d22-0f59-4140-9076-c61f61740f76/notifications"
      }
    },
    {
      "id": "a5c98193-d845-4898-b69a-2f735aa4bfc3",
      "timestamp": "2016-10-20T17:29:44.204Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "shutdown",
      "object": {
        "id": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "type": "vehicle"
      },
      "meta": null,
      "links": {
        "self": "https://events.vin.li/api/v1/events/a5c98193-d845-4898-b69a-2f735aa4bfc3",
        "notifications": "https://events.vin.li/api/v1/events/a5c98193-d845-4898-b69a-2f735aa4bfc3/notifications"
      }
    },
    {
      "id": "7933c50a-e422-3ff9-v51d-cddc443f1a88",
      "timestamp": "2016-10-20T14:00:19.547Z",
      "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
      "eventType": "rule-leave",
      "object": {
        "id": "6cf4ddaa-3c16-439c-bc3f-6bb9a7dcb7fd",
        "type": "rule"
      },
      "meta": {
        "direction": "leave",
        "firstEval": false,
        "rule": {
          "id": "6cf4ddaa-3c16-439c-bc3f-6bb9a7dcb7fd",
          "name": "new geofence",
          "deviceId": "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
          "boundaries": [
            {
              "id": "5714379f-c5f3-4052-ad5d-0aa22032475b",
              "type": "radius",
              "radius": 312.33,
              "lon": -96.7899370193481,
              "lat": 32.8242218079282
            }
          ],
          "evaluated": true,
          "covered": false,
          "createdAt": "2016-07-23T05:41:28.179+00:00",
          "links": {
            "self": "https://rules.vin.li/api/v1/rules/6cf4ddaa-3c16-439c-bc3f-6bb9a7dcb7fd",
            "events": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/events?type=rule-*&objectId=6cf4ddaa-3c16-439c-bc3f-6bb9a7dcb7fd",
            "subscriptions": "https://events.vin.li/api/v1/devices/68d489c0-d7a2-11e3-9c1a-0800200c9a66/subscriptions?objectType=rule&objectId=6cf4ddaa-3c16-439c-bc3f-6bb9a7dcb7fd"
          }
        },
        "message": {
          "id": "645ff3f0-c8a9-4538-b903-2a8b29087635",
          "timestamp": "2016-10-20T14:00:19.547Z",
          "snapshot": {
            "location": {
              "lat": 41.502994,
              "lon": -71.314856
            },
            "accel": {
              "maxZ": -4.137202,
              "maxX": 1.379067,
              "maxY": -5.439654,
              "minX": 0.229845,
              "minY": -8.236096,
              "minZ": -6.473954
            },
            "massAirFlow": 18.69,
            "rpm": 1802,
            "vehicleSpeed": 13,
            "intakeManifoldPressure": 60,
            "fuelAirCommandedEquivalenceRatio": 0.973236083984375
          }
        }
      },
      "links": {
        "self": "https://events.vin.li/api/v1/events/7933c50a-e422-3ff9-v51d-cddc443f1a88",
        "notifications": "https://events.vin.li/api/v1/events/7933c50a-e422-3ff9-v51d-cddc443f1a88/notifications"
      }
    }
  ],
  "meta": {
    "pagination": {
      "remaining": 1214,
      "until": "2016-10-20T18:09:29.977Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 20,
      "sortDir": "desc",
      "links": {
        "prior": "https://events.vin.li/api/v1/vehicles/48ef1264-7fd2-4319-8789-g9a6b85b7a8f/events?until=1476971981756"
      }
    }
  }
}
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",
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "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 events, your application should subscribe to events by type for each device or vehicle.

Each Subscription relates to a given event type or class of events from a given Device/Vehicle and specifies the external URL that will be called when the event occurs and any additional “App Data” that should be included.

Notification Payloads

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. Below are several examples of Notifications for different types of Events.

Rule-Leave
{
    "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\"}"
        }
    }
}
Collision
{
  "notification": {
    "event": {
      "id": "edae9b7a-c447-442d-aead-ee0bf4f5e6b4",
      "timestamp": "2016-08-22T23:12:59.607Z",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "stored": "2016-08-22T23:13:15.167Z",
      "storageLatency": 15560,
      "eventType": "collision",
      "object": {
        "id": "ba8d8890-3d4d-413a-ad8e-a3269d990e91",
        "type": "vehicle"
      },
      "links": {
        "self": "http://10.200.37.245:30003/api/v1/events/edae9b7a-c447-442d-aead-ee0bf4f5e6b4",
        "notifications": "http://10.200.37.245:30003/api/v1/events/edae9b7a-c447-442d-aead-ee0bf4f5e6b4/notifications"
      }
    },
    "subscription": {
      "id": "f4366076-afe0-4b05-83ff-55b6ddde0984",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "eventType": "collision",
      "url": "https://myapp.com/notifications",
      "appData": null,
      "createdAt": "2016-08-22T23:11:36.814Z",
      "updatedAt": "2016-08-22T23:11:36.814Z",
      "links": {
        "self": "http://10.200.37.245:30003/api/v1/subscriptions/f4366076-afe0-4b05-83ff-55b6ddde0984",
        "notifications": "http://10.200.37.245:30003/api/v1/subscriptions/f4366076-afe0-4b05-83ff-55b6ddde0984/notifications"
      }
    }
  }
}
DTC-On
{
  "notification": {
    "event": {
      "id": "aa2842c3-b647-48a1-80f1-cc6019ce387c",
      "timestamp": "2016-08-22T23:12:20.003Z",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "stored": "2016-08-22T23:12:22.036Z",
      "storageLatency": 2033,
      "eventType": "dtc-on",
      "meta": {
        "code": "313cc7d7-1ac6-491c-9e02-a3d08e62984a"
      },
      "object": {
        "id": "ba8d8890-3d4d-413a-ad8e-a3269d990e91",
        "type": "vehicle"
      },
      "links": {
        "self": "http://10.220.0.66:30003/api/v1/events/aa2842c3-b647-48a1-80f1-cc6019ce387c",
        "notifications": "http://10.220.0.66:30003/api/v1/events/aa2842c3-b647-48a1-80f1-cc6019ce387c/notifications"
      }
    },
    "subscription": {
      "id": "e480343c-172a-41da-81ef-ce7950790ee0",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "eventType": "dtc-on",
      "url": "https://myapp.com/notifications",
      "appData": null,
      "createdAt": "2016-08-22T23:09:22.023Z",
      "updatedAt": "2016-08-22T23:09:22.023Z",
      "links": {
        "self": "http://10.220.0.66:30003/api/v1/subscriptions/e480343c-172a-41da-81ef-ce7950790ee0",
        "notifications": "http://10.220.0.66:30003/api/v1/subscriptions/e480343c-172a-41da-81ef-ce7950790ee0/notifications"
      }
    }
  }
}
Distance-Trigger
{
  "notification": {
    "event": {
      "id": "4449b8a1-88ce-479e-83ba-46d233895519",
      "timestamp": "2016-07-18T22:32:41.737Z",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "stored": "2016-07-18T22:32:41.860Z",
      "storageLatency": 123,
      "eventType": "distance-trigger",
      "meta": {
        "odometerTrigger": {
          "id": "bc043c26-3d79-44ce-b08e-8193f4c5e493",
          "vehicleId": "03d8ec74-523b-4ff7-8f6f-8228146b93b9",
          "type": "specific",
          "threshold": 24146537.36,
          "events": 0,
          "links": {
            "vehicle": "https://platform.vin.li/api/v1/vehicles/03d8ec74-523b-4ff7-8f6f-8228146b93b9"
          }
        },
        "estimatedOdometer": 24158103.340000004
      },
      "object": {
        "id": "bc043c26-3d79-44ce-b08e-8193f4c5e493",
        "type": "odometer-trigger"
      },
      "links": {
        "self": "http://10.200.37.245:30003/api/v1/events/4449b8a1-88ce-479e-83ba-46d233895519",
        "notifications": "http://10.200.37.245:30003/api/v1/events/4449b8a1-88ce-479e-83ba-46d233895519/notifications"
      }
    },
    "subscription": {
      "id": "2fc61637-8e2d-465f-8518-cce48f205faf",
      "deviceId": "eb4f66ec-4050-4052-9559-baf5d8eb8511",
      "eventType": "distance-trigger",
      "url": "https://myapp.com/notifications",
      "appData": null,
      "createdAt": "2016-07-18T22:09:34.704Z",
      "updatedAt": "2016-07-18T22:09:34.704Z",
      "links": {
        "self": "http://10.200.37.245:30003/api/v1/subscriptions/2fc61637-8e2d-465f-8518-cce48f205faf",
        "notifications": "http://10.200.37.245:30003/api/v1/subscriptions/2fc61637-8e2d-465f-8518-cce48f205faf/notifications"
      }
    }
  }
}
Startup
{
  "notification": {
    "event": {
      "id": "5eca3320-7037-4eaf-8cea-08328bf25408",
      "timestamp": "2016-08-24T20:26:04.816Z",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "stored": "2016-08-24T20:26:08.809Z",
      "storageLatency": 3993,
      "eventType": "startup",
      "object": {
        "id": "2271db32-aa6c-4ae5-9d68-f371eb3d1cfb",
        "type": "vehicle"
      },
      "links": {
        "self": "http://10.220.0.66:30003/api/v1/events/5eca3320-7037-4eaf-8cea-08328bf25408",
        "notifications": "http://10.220.0.66:30003/api/v1/events/5eca3320-7037-4eaf-8cea-08328bf25408/notifications"
      }
    },
    "subscription": {
      "id": "050ea013-33f2-49ae-bcf2-f23032e6ca30",
      "deviceId": "4bffefbb-9fba-43ee-aebe-ed7f7f2fae84",
      "eventType": "startup",
      "url": "https://myapp.io/startup",
      "object": {
        "id": "2271db32-aa6c-4ae5-9d68-f371eb3d1cfb",
        "type": "vehicle"
      },
      "appData": null,
      "createdAt": "2016-08-24T20:25:18.017Z",
      "updatedAt": "2016-08-24T20:25:18.017Z",
      "links": {
        "self": "http://10.220.0.66:30003/api/v1/subscriptions/050ea013-33f2-49ae-bcf2-f23032e6ca30",
        "notifications": "http://10.220.0.66:30003/api/v1/subscriptions/050ea013-33f2-49ae-bcf2-f23032e6ca30/notifications"
      }
    }
  }
}

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 Notification including a representation 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 for a Device

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.

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"
  }
}
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"
        }
    }
}
Create a Subscription for a Vehicle
POST https://events.vin.li/api/v1/vehicles/48ef1264-7fd2-4319-8789-g9a6b85b7a8f/subscriptions
Accept: application/json
Content-Type: application/json

{
  "subscription" : {
    "eventType" : "startup",
    "url": "https://myapp.com/notifications"
  }
}
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://events.vin.li/api/v1/subscriptions/87965f0f-d468-48e1-9585-69d547900058

{
    "subscription" : {
        "id": "87965f0f-d468-48e1-9585-69d547900058",
        "eventType": "startup",
        "url": "https://myapp.com/notifications",
        "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
        "object": null,
        "appData": null,
        "createdAt": "2016-01-25T12:54:09.876Z",
        "updatedAt": "2016-01-25T12:54:09.876Z",
        "links": {
            "self": "https://events.vin.li/api/v1/subscriptions/87965f0f-d468-48e1-9585-69d547900058",
            "notifications": "https://events.vin.li/api/v1/subscriptions/87965f0f-d468-48e1-9585-69d547900058/notifications"
        }
    }
}
Create a Subscription for a Rule

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.

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"
    }
  }
}
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
GET https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions
Accept: application/json
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 All Subscriptions for a Vehicle
GET https://events.vin.li/api/v1/vehicles/48ef1264-7fd2-4319-8789-g9a6b85b7a8f/subscriptions
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "subscriptions": [
        {
            "id": "917fb546-5666-4fdd-aed6-53fa099b313b",
            "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
            "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"
            }
        },
        {
            "id": "829fb457-4757-4fdd-aed6-53fa108b402b",
            "eventType": "startup",
            "url": "https://myapp.com/notifications",
            "vehicleId": "48ef1264-7fd2-4319-8789-g9a6b85b7a8f",
            "object": null,
            "appData": null,
            "createdAt": "2016-01-25T19:35:35.148Z",
            "updatedAt": "2016-01-25T19:35:35.148Z",
            "links": {
              "self": "https://events.vin.li/api/v1/subscriptions/829fb457-4757-4fdd-aed6-53fa108b402b",
              "notifications": "https://events.vin.li/api/v1/subscriptions/829fb457-4757-4fdd-aed6-53fa108b402b/notifications"
            }
        },
        ...
    ],
    "meta": {
        "pagination": {
            "total": 80,
            "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
GET https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b
Accept: application/json
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.

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\"}",
  }
}
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
DELETE https://events.vin.li/api/v1/subscriptions/917fb546-5666-4fdd-aed6-53fa099b313b
Accept: application/json
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": {
        "remaining": 2,
        "until": "2016-09-15T18:38:44.036Z",
        "since": "1970-01-01T00:00:00.000Z",
        "limit": 20,
        "sortDir": "desc",
        "links": {
          "prior": "https://events.vin.li/api/v1/subscriptions/f4366076-afe0-4b05-83ff-55b6ddde0984/notifications?until=1473961364647"
          }
        }
      }
    }
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": {
        "remaining": 0,
        "until": "2016-09-15T20:19:32.978Z",
        "since": "1970-01-01T00:00:00.000Z",
        "limit": 20,
        "sortDir": "desc",
        "links": {}
        }
      }
    }

Rule Service

The Vinli Rule Service creates event subscriptions based on:

  • vehicle parameters
  • geofences

The Rules Service evaluates a vehicle’s location and operating parameters. When the vehicle satisfies all of the boundary conditions for a Rule, the Event Service notifies subscribed applications.

Rules

A Rule contains:

  1. a Device identifier

  2. a collection of Boundaries for the Device

  3. a state which is always exactly one of:

    • “unevaluated” meaning not enough geospatial data is available
    • “uncovered” meaning at least one of the boundaries conditions is unsatisfied
    • “covered” meaning that all of the boundary conditions are satisfied

A Rule is “covered” when all boundary conditions are true. A Rule is “uncovered” when at least one boundary condition is false. When there is insufficient data to determine whether a Rule is “covered” or “uncovered” the Rule’s state is “unevaluated”.

When sufficient geospatial data is available to change state, the Rule Service:

  • changes the state of the Rule to “covered” or “uncovered”, and
  • creates either a “rule-entry” or “rule-leave” event for applications

For example, suppose an app establishes a Boundary condition around the home of a vehicle owner. When the owner drives home from work, the Rule Service detects that a geospatial Boundary condition is satisfied, The service sets the Rule state to “covered” and then sends a “rule-entry” event to the app.

Likewise, when the vehicle owner leaves home for work, the Rule Service detects that a geospatial Boundary condition is no longer met. The service sets the Rule state to “uncovered” and then sends a “rule-leave” event to the app.

Applications can subscribe to these events in three ways:

  • to the “rule-entry” only
  • to the “rule-leave” only
  • or to both with “rule-*”

Boundaries

A Boundary is either:

  • a geospatial boundary that defines a region on the Earth’s surface, or
  • a parametric boundary that defines a range for some vehicle parameter

A geospatial boundary defines a circular geographic region by specifying:

  • a single geographic point, and
  • a radius in meters

A parametric boundary specifies either:

  • a bounded range, such as “RPM between 2000 and 4000”, or
  • an unbounded range, such as “RPM greater than 3500”

A Rule is “covered” when all Boundary conditions are true. This fact has important implications for rule design.

  • Suppose an app developer adds two disjoint geospatial boundaries to a rule. The rule can never enter the “covered” state nor ever fire a “rule-entry” or “rule-leave” event. It will forever remain in the “unevaluated” state. Because the Device can only be in one location at a time, at best it can only satisfy one of the boundary conditions but never both.
  • Similarly, a rule will never fire an event if the rule contains two disjoint parametric boundaries for the same vehicle parameter. For example, “RPM greater than 3500” and “RPM less than 2000” will forever remain in the “unevaluated” state.

Because of these implications, the Rule Service allows at most one geospatial boundary in a Rule. This eliminates the problem of disjoint geospatial regions. However, app developers must still avoid creating disjoint parametric boundaries.

Rule API

The Rule Service allows your application to manage the rules for devices.

Rules are immutable. Once created, a rule cannot be modified. To change a Rule, your app must delete an existing rule, and then create another one. Immutability ensures that a Rule is always in a perfectly consistent state.

List all Rules for a Device
Request
GET https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "rules" : [
    {
      "id" : "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "name" : "Speed over 70mph",
      "deviceId" : "de01abb1-453d-4293-831a-f0d804b48fdf",
      "evaluated": true,
      "covered": false,
      "createdAt": "2015-06-01T21:26:51.086Z",
      "links" : {
        "self" : "https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66",
        "events": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/events?type=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66",
        "subscriptions": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?objectType=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66"
      }
    },
   ...
  ],
  "meta" : {
    "pagination" : {
      "total" : 1431,
      "offset" : 0,
      "limit" : 20,
      "links" : {
        "first" : "https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules?offset=0&limit=20",
        "last" : "https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules?offset=1420&limit=20",
        "next" : "https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules?offset=20&limit=20"
      }
    }
  }
}
Get a Specific Rule
Request
GET https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "rule" : {
    "id" : "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
    "name" : "Speed over 35mph near Superdome",
    "boundaries" : [
      {
        "type" : "parametric",
        "parameter" : "vehicleSpeed",
        "min" : 35
      },
      {
        "type" : "radius",
        "lon" : -90.0811,
        "lat" : 29.9508,
        "radius" : 500
      }
    ],
    "deviceId" : "de01abb1-453d-4293-831a-f0d804b48fdf",
    "links" : {
      "self" : "https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "events": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/events?type=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "subscriptions": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?objectType=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66"
    }
  }
}
Create a Rule for a Device
Request
POST https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules
Accept: application/json
Content-Type: application/json

{
  "rule" : {
    "name" : "Speed over 35mph near Superdome",
    "boundaries" : [
      {
        "type" : "parametric",
        "parameter" : "vehicleSpeed",
        "min" : 35,
        "max" : null
      },
      {
        "type" : "radius",
        "lon" : -90.0811,
        "lat" : 29.9508,
        "radius" : 500
      }
    ]
  }
}
Response
HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66

{
  "rule" : {
    "id" : "68d489c0-d7a2-11e3-9c1a-0800200c9a66",
    "name" : "Speed over 35mph near the Superdome",
    "boundaries" : [
      {
        "type" : "parametric",
        "parameter" : "vehicleSpeed",
        "min" : 35
      },
      {
        "type" : "radius",
        "lon" : -90.0811,
        "lat" : 29.9508,
        "radius" : 500
      }
    ],
    "deviceId" : "de01abb1-453d-4293-831a-f0d804b48fdf",
    "links" : {
      "self" : "https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "events": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/events?type=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66",
      "subscriptions": "https://events.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/subscriptions?objectType=rule&objectId=68d489c0-d7a2-11e3-9c1a-0800200c9a66"
    }
  }
}

We also support polygon geofences.

POST https://rules.vin.li/api/v1/devices/de01abb1-453d-4293-831a-f0d804b48fdf/rules
Accept: application/json
Content-Type: application/json

{
  "rule": {
          "name": "Polygon Boundary Example",
          "boundaries": [{
                  "type": "polygon",
                  "coordinates": [
                          [
                                  [-96.7910099029541, 32.7838830957529],
                                  [-96.7893073707819, 32.78267779866992],
                                  [-96.79272651672362, 32.776558606411804],
                                  [-96.79242610931395, 32.78189868775024],
                                  [-96.79718971252441, 32.78254813524194],
                                  [-96.7910099029541, 32.7838830957529]
                          ]
                  ]
          }]
  }
}
Delete a Rule
Request
DELETE https://rules.vin.li/api/v1/rules/68d489c0-d7a2-11e3-9c1a-0800200c9a66
Response
HTTP/1.1 204 NO CONTENT

Diagnostic Services

In addition to transmitting real-time vehicle telemetry information, the Vinli Device interrogates the vehicle for the status of the malfunction indicator lamp (MIL) or “Check Engine Light”. If the device detects that the MIL is illuminated, it requests the active diagnostic trouble codes (DTCs) for the vehicle. All of this information is sent to the Vinli Platform and can be accessed via the Diagnostic Service API.

Working with DTC Codes

Get a list of DTCs for a Vehicle

This provides historical record of 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.li/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": {}
    }
  }
}
Query by State

A request like GET https://diagnostic.vin.li/api/v1/vehicles/47fa348e-c3fa-4cad-8272-61940eae7748/codes will return all DTCs for a given vehicle, but sometimes you only want DTCs that are currently active (or inactive). To do this, simply add the state query parameter.

state will accept the following options:
  • active
  • inactive
  • all (which is the default)

Here’s an example:

GET https://diagnostic.vin.li/api/v1/vehicles/47fa348e-c3fa-4cad-8272-61940eae7748/codes?state=active
Accept: application/json
Get a Specific DTC

This route returns a specific DTC occurrence.

Request
GET https://diagnostic.vin.li/api/v1/codes/313cc7d7-1ad6-491k-9e02-a3f48e62984a
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": {
    "id": "313cc7d7-1ad6-491k-9e02-a3f48e62984a",
    "make": "generic",
    "system": "powertrain",
    "subsystem": "Fuel and air metering",
    "number": "P0087",
    "description": "Fuel Rail/System Pressure - Too Low Bank 1",
    "links": {
      "self": "https://diagnostic.vin.li/api/v1/codes/313cc7d7-1ad6-491k-9e02-a3f48e62984a"
    }
  }
}
Battery Status
This provides a general health status for a vehicle’s battery. Possible statuses include:
  • green indicates that the battery is likely to start
  • yellow indicates that the battery may have issues starting
  • red indicates a battery is likely to not start
  • null indicates that Vinli could not determine the status based on the data provided
Request
GET https://diagnostic.vin.li/api/v1/vehicles/38ff2972-7fd2-4319-8389-b9a8b84a7c8f/battery_statuses/_current
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "batteryStatus": {
    "status": "green",
    "timestamp": "2016-08-21T20:00:22.680Z"
  }
}

DTC Info Service

Get Information About a DTC Code

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://172.17.0.18:80/api/v1/codes?offset=0&limit=20",
        "last": "http://172.17.0.18:80/api/v1/codes?offset=0&limit=20"
      }
    }
  }
}

Distance Service

The Distance Service is designed to enable odometer based features. Using distance service it is possible to:
  • Generate a ‘best guess’ odometer reading for a given point in time
  • Submit odometer readings to the Vinli Platform
  • Create odometer triggers for mileage milestones or recurring mileage intervals.

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

Trip Service

The Vinli device detects vehicle ignition and shutdown and sends those events to the platform. From these events, it is possible to organize the telemetry data into logical “Trips” for organizing users’ activities in your application. The Trip Service provides access to a catalog of these trips by device or by vehicle and provides mirrors of the Telemetry Services methods centered around these trips.

It’s important to 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.

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.

Note 1: Trips are sometimes created asynchronously–either because they have to be constructed by post-processing or after bulk data upload for a given device. Note 2: Only trips for the 20 most recent devices that have been in the vehicle will be returned.

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": 38.288,
        "averageMovingSpeed": 19.9488,
        "averageSpeed": 16.7443,
        "comprehensiveLocations": true,
        "distance": 2467.1,
        "distanceByGPS": 2467.1,
        "distanceByVSS": 2121.67,
        "duration": 503340,
        "fuelConsumed": 0.34644,
        "fuelEconomy": 14.4982,
        "hardAccelCount": 0,
        "hardBrakeCount": 0,
        "locationCount": 433,
        "maxSpeed": 45,
        "messageCount": 557,
        "stdDevMovingSpeed": 12.2787,
        "stopCount": 14,
        "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/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
  • comprehensiveLocations - the trip has substantial GPS coverage
  • 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
  • locationCount - the number of messages in the trip containing locations
  • maxSpeed - the maximum speed (in kph) reported for the Vehicle during the trip
  • messageCount - the total number of messages comprising 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
  • substantial - boolean, indicating whether or not a trip had enough messages and data to be considered substantial

All of the detailed information listed in the above verbiage is available via the get trips by device or get trips by vehicle.

  • fuelEconomy invokes an operation to get the fuel type of a trip. fuelEconomy uses gasoline as the default fuel type. However, diesel will be set as the fuel type (and corresponding diesel values for calculations) if it is detected in a trip.

The trip document also includes short information about the telemetry associated with it, namely:

  • startPoint - coordinates of the position where the trip was initiated
  • stopPoint - coordinates of the position where the trip was concluded
  • preview - encoded string of the polyline representing the trip (usable in map services such as Google Maps, Mapbox, ...)
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": 38.288,
      "averageMovingSpeed": 19.9488,
      "averageSpeed": 16.7443,
      "comprehensiveLocations": true,
      "distance": 2467.1,
      "distanceByGPS": 2467.1,
      "distanceByVSS": 2121.67,
      "duration": 503340,
      "fuelConsumed": 0.34644,
      "fuelEconomy": 14.4982,
      "hardAccelCount": 0,
      "hardBrakeCount": 0,
      "locationCount": 433,
      "maxSpeed": 45,
      "messageCount": 557,
      "stdDevMovingSpeed": 12.2787,
      "stopCount": 14,
      "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"
    }
  }
}

Behavioral Services

Based on long-term driving data, Vinli calculates and keeps track of behavioral statistics for particular devices and vehicles.

The scores reported by Behavioral Services are meant to convey a driver’s overall risk categorization based on historical data gathered by the Vinli device; they are by no means a be-all-end-all measure of the likelihood that a driver will be involved in a collision. Safe driving involves so many other factors that are not measurable by the Vinli Device; however, Behavioral Services attempts to categorize risk based on what data are available.

The results of these analysis are “Report Cards” for both a single Trip and for a Device’s lifetime. Each report is based on the results of three categories of behavior:

  • Driver Behavior - the risk based on driving habits detected from the vehicle telemetry including aggressive inputs, erratic driving, speeding, etc.
  • Vehicle Condition - the risk based on data gathered about vehicle’s maintenance condition
  • Travel Patterns - the risk based on where the driver travels most frequently

Report Card Service

The Driver Report Card contains the letter grades for trips associated with a device. They are representd as school-like grades such as A or C.

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://behavioral.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.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards?until=1439418498459"
      }
    }
  }
}
Report Cards for a Vehicle

Returns a Report Card based on historical data for a specified period for a given vehicle. 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://behavioral.vin.li/api/v1/vehicles/ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55/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/vehicles/ca10cd7a-d2a5-4bb3-b47b-2aa0b8848f55/report_cards?until=1439418498459"
      }
    }
  }
}
Lifetime Report Card for a Device

Returns a Report Card based on all historical data available for a given Device, with a trip sample size that shows how many trips were used to calculate the overall grade.

Request
GET https://behavioral.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"
  },

  "tripSampleSize": 1131,
  "gradeCount": {
    "B": "108",
    "F": "1",
    "I": "9",
    "C": "24",
    "A": "1000",
    "D": "1"
  }
}
Get a Report Card for a Time Segment

Returns a Report Card based on all historical data available for a given Device or Vehicle, within a time segment that you’ve defined using since and until query parameters.

This is helpful if you want to present the user something like, “Last week your driving score was a C”.

Note that while tripSampleSize reflects the count of trips within the time segment, gradeCount still reflects the lifetime sample.

Reqest
GET https://behavioral.vin.li/api/v1/devices/fe4bbc20-cc90-11e3-8e05-f3abac5b6b58/report_cards/overall?since=2016-12-05&until=2016-12-13
Response
  "tripSampleSize": 117,
  "gradeCount:" {
    "B": "21",
    "F": "2",
    "I": "4",
    "C": "19",
    "A": "68",
    "D": "3"
  }
}
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://behavioral.vin.li/api/v1/trips/b9e58eb4-0743-45e9-b9c6-86500f5412bb/report_cards/_current
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "reportCard" : {
    "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"
    }
  }
}
Get a Specific Report Card

Returns a Report Card based on a specified report card id. 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://behavioral.vin.li/api/v1/report_cards/549d628c-48dc-412d-8087-44a9f82f187e
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "reportCard" : {
    "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 Services

The Vinli Device is able to detect when a collision occurs based on internal sensor and select vehicle telemetry data. Using Vinli’s Safety Services, your application can access collision history and retrieve detailed collision details.

Event Services can be used to set up subscriptions to collision events, which can be used

Note: It is extremely important to remind the user to call their local emergency services number (9-1-1, 1-1-2, etc.). Vinli’s Safety Services, while built to be as reliable as possible, should not be used in place of standard emergency procedures.

Collision Service

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",
      "deviceId": "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
      "vehicleId": "e619dc1d-b760-410f-b809-2578df22a755",
      "timestamp": "2016-12-21T18:37:30.938Z",
      "location" : {
        "latitude" : 32.766392,
        "longitude" : -96.917009
      },
      "links": {
        "self": "https://safety.vin.li/api/v1/collisions/561f0fa0-3231-11e4-8c21-0800200c9a66",
        "device": "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755"
      }
    },
    {
      "id": "014f029c-a5b6-4e15-f0dd-707920aa6b6f",
      "deviceId": "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
      "vehicleId": "e619dc1d-b760-410f-b809-2578df22a755",
      "timestamp": "2016-12-21T18:36:41.938Z",
      "location" : {
        "latitude" : 32.766392,
        "longitude" : -96.917009
      },
      "links": {
        "self": "https://safety.vin.li/api/v1/collisions/014f029c-a5b6-4e15-f0dd-707920aa6b6f",
        "device": "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755"
      }
    }
  ],
  "meta": {
    "pagination": {
      "remaining": 6,
      "until": "2016-09-19T22:48:40.524Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 2,
      "sortDir": "desc",
      "links": {
        "prior": "https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions?until=1473961364647"
      }
    }
  }
}
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",
      "deviceId": "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
      "vehicleId": "e619dc1d-b760-410f-b809-2578df22a755",
      "timestamp": "2016-12-21T18:37:30.938Z",
      "location" : {
        "latitude" : 32.766392,
        "longitude" : -96.917009
      },
      "links": {
        "self": "https://safety.vin.li/api/v1/collisions/561f0fa0-3231-11e4-8c21-0800200c9a66",
        "device": "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755"
      }
    },
    {
      "id": "014f029c-a5b6-4e15-f0dd-707920aa6b6f",
      "deviceId": "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
      "vehicleId": "e619dc1d-b760-410f-b809-2578df22a755",
      "timestamp": "2016-12-21T18:36:41.938Z",
      "location" : {
        "latitude" : 32.766392,
        "longitude" : -96.917009
      },
      "links": {
        "self": "https://safety.vin.li/api/v1/collisions/014f029c-a5b6-4e15-f0dd-707920aa6b6f",
        "device": "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
        "vehicle": "https://platform.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755"
      }
    }
  ],
  "meta": {
    "pagination": {
      "remaining": 6,
      "until": "2016-09-19T22:48:40.524Z",
      "since": "1970-01-01T00:00:00.000Z",
      "limit": 2,
      "sortDir": "desc",
      "links": {
        "prior": "https://safety.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66/collisions?until=1473961364647"
      }
    }
  }
}
Get a Specific Collision
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": "014f029c-a5b6-4e15-f0dd-707920aa6b6f",
    "deviceId": "8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
    "vehicleId": "e619dc1d-b760-410f-b809-2578df22a755",
    "timestamp": "2016-12-21T18:36:41.938Z",
    "location" : {
      "latitude" : 32.766392,
      "longitude" : -96.917009
    },
    "links": {
      "self": "https://safety.vin.li/api/v1/collisions/014f029c-a5b6-4e15-f0dd-707920aa6b6f",
      "device": "https://platform.vin.li/api/v1/devices/8b8a1810-d6d8-11e3-9c1a-0800200c9a66",
      "vehicle": "https://platform.vin.li/api/v1/vehicles/e619dc1d-b760-410f-b809-2578df22a755"
    }
  }
}

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

Virtual Vinli Service

Use the Virtual Vinli service to get sample vehicle data for your app. With virtual vehicle data, you can test, prototype, and learn the Vinli platform. It’s simple.

  1. Get dummy device data from the Virtual Vinli service.
  2. Add the dummy device to your MyVinli account, under New Device.
  3. Get the available routes from the Virtual Vinli service.
  4. Select and run a route. You now have a virtual vehicle generating data.
  5. Use standard Vinli services to do test and prototype with the data.

See next:

Virtual Vinli Dummy Service

Create a Dummy Device
Request
POST https://dummies.vin.li/api/v1/dummies
Content-Type: application/json

{
   "dummy":{
      "name":"YourDummyName"
   }
}
Response
{
  "dummy": {
    "id": "f57d3b8f-6e2d-4038-a54a-bfbd9b52bcf3",
    "name": "YourDummyName",
    "deviceId": "5067097d-d9b0-49d7-ac06-badd1030670e",
    "caseId": "VV4G86Z",
    "links": {
      "self": "https://dummies.vin.li/api/v1/dummies/f57d3b8f-6e2d-4038-a54a-bfbd9b52bcf3",
      "runs": "https://dummies.vin.li/api/v1/dummies/f57d3b8f-6e2d-4038-a54a-bfbd9b52bcf3/runs",
      "device": "https://platform.vin.li/api/v1/devices/5067097d-d9b0-49d7-ac06-badd1030670e",
      "messages": "https://telemetry.vin.li/api/v1/devices/5067097d-d9b0-49d7-ac06-badd1030670e/messages",
      "events": "https://events.vin.li/api/v1/devices/5067097d-d9b0-49d7-ac06-badd1030670e/events"
    }
  }
}
List Dummy Devices
Request
GET https://dummies.vin.li/api/v1/dummies
Accept: application/json
Response
{
  "dummies": [
    {
      "id": "m2900t1f-7ca5-4641-j4b6-623cae742aa5",
      "name": "84_Sheepdog",
      "deviceId": "7gka0j62-858f-51b2-a5b7-br13c469158k",
      "caseId": "VV6L0FS",
      "links": {
        "self": "https://dummies.vin.li/api/v1/dummies/m2900t1f-7ca5-4641-j4b6-623cae742aa5",
        "runs": "https://dummies.vin.li/api/v1/dummies/m2900t1f-7ca5-4641-j4b6-623cae742aa5/runs",
        "device": "https://platform.vin.li/api/v1/devices/7eac0d62-854f-41c1-a5b2-ba13c460058a",
        "messages": "https://telemetry.vin.li/api/v1/devices/7eac0d62-854f-41c1-a5b2-ba13c460058a/messages",
        "events": "https://events.vin.li/api/v1/devices/7eac0d62-854f-41c1-a5b2-ba13c460058a/events"
      }
    },
    {
      "id": "4f1c5c34-2b61-4dhe-824b-2c517f69bdwf",
      "name": "VV_4_the_docs",
      "deviceId": "21f1688b-0374-41y3-9d08-g2fcaac53f31",
      "caseId": "VVA39E1",
      "links": {
        "self": "https://dummies.vin.li/api/v1/dummies/4g1c5v34-2b61-4dhe-824b-2c517f69bdwf",
        "runs": "https://dummies.vin.li/api/v1/dummies/4g1c5v34-2b61-4dhe-824b-2c517f69bdwf/runs",
        "device": "https://platform.vin.li/api/v1/devices/21f1688b-0374-41y3-9d08-g2fcaac53f31",
        "messages": "https://telemetry.vin.li/api/v1/devices/21f1688b-0374-41y3-9d08-g2fcaac53f31/messages",
        "events": "https://events.vin.li/api/v1/devices/21f1688b-0374-41y3-9d08-g2fcaac53f31/events"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 20,
      "offset": 0,
      "links": {
        "first": "https://dummies.vin.li/api/v1/dummies?offset=0&limit=20",
        "last": "https://dummies.vin.li/api/v1/dummies?offset=0&limit=20"
      }
    }
  }

Virtual Vinli Routes

Virtual Vinli uses pre-recorded drives, known as Dummy Routes, that can be virtually driven by Dummy Devices, simulating test data and various driving scenarios for your app.

List Dummy Routes
Request
GET https://dummies.vin.li/api/v1/routes
Accept: application/json
Response
{
  "routes": [
    {
      "id": "8e90cf47-c6c1-486d-9ba8-194f569c7309",
      "name": "DFW - Back Home",
      "description": "DFW residential streets, start away and goes home quickly. Is the reverse of \"DFW - Home Loop 1 of 3\"; combine with that route to make a back and forth trip. Starts at (-96.783485, 32.834532). Will leave a geofence at that location with a 50m radius in Z seconds.  Will enter a second geofence at (-96.787547, 32.834541) in Z seconds. Stops at (-96.787547, 32.834541).",
      "messageCount": 28,
      "locationCount": 28,
      "distanceByGPS": 387.85,
      "distanceByVSS": 446.427,
      "duration": 86843,
      "preview": "y~kgEv_vmQLfBM|AB~@I~@Dt@AtHD~@ARGLD^AC",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/8e90cf47-c6c1-486d-9ba8-194f569c7309"
      }
    },
    {
      "id": "a9f09ad2-05d6-4b8d-b218-2e65a3229e8e",
      "name": "DFW - Circle the Block",
      "description": "Starts at (-96.787427, 32.83456)  will leave a geofence at that location with a 50m radius in Z seconds.  Will reenter same geo fence in Z seconds. Stops at (-96.787501, 32.834597).",
      "messageCount": 43,
      "locationCount": 43,
      "distanceByGPS": 588.761,
      "distanceByVSS": 625.607,
      "duration": 135665,
      "preview": "__lgElxvmQ@fAC`DJ|@_A^qAAe@LOk@A{CBwACaAB_@bCBbAEF\\Ih@OCCE",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/a9f09ad2-05d6-4b8d-b218-2e65a3229e8e"
      }
    },
    {
      "id": "64803498-cc0d-4724-99ef-e0d32d527670",
      "name": "DFW - Downtown Route 1",
      "description": "Out and about in downtown Dallas.  This route includes MAF and several other low-frequency parameters.",
      "messageCount": 139,
      "locationCount": 120,
      "distanceByGPS": 4506.49,
      "distanceByVSS": 8904.45,
      "duration": 499277,
      "preview": "wb_gElezmQ?wCm@sC{F}HiDiEq@uAsA}AeDsEyCgJKgCk@uDUaCa@cC_@kDYcFAiBOaCGeC_@eI_@oDi@wDiBgFw@wAuAiBqDeEaEmF_BaAoBq@cDSsB~BwApBsAdCaDpGyB`GuAtC{@`Dg@bIZ|Bn@hEOQJ?E?BbAN|@Nb@HbA\\~AFrBH`@LzAHf@r@LZAj@D\\Or@Cp@a@\\KCEABBDAEB?\\]g@}C]gCBDDEAEt@g@Rw@AWOm@V]G]MOOFCFBBDE@N?I",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/64803498-cc0d-4724-99ef-e0d32d527670"
      }
    },
    {
      "id": "7e582c36-281c-4551-b54a-0a49cadcb665",
      "name": "DFW - Downtown Route 2",
      "description": "Drives on city streets from the Omni hotel to local farmers market in Dallas",
      "messageCount": 88,
      "locationCount": 88,
      "distanceByGPS": 1718.89,
      "distanceByVSS": 1808.95,
      "duration": 1615955,
      "preview": "yp`gEj_zmQM?qAY[wAIkADy@WaCM{@Au@SqAO_BFs@Pm@?Y`@i@Zu@Lw@JcALw@J[n@Yz@Ql@Yd@s@pCoDn@q@jAwAGNBBEIHg@Oa@i@q@e@Uk@cBuAkBAGHBMGEKKKgAw@q@mAcA}@GOgAoAUc@u@q@Qe@iBsBs@o@CWOQc@aASq@CaADYFL",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/7e582c36-281c-4551-b54a-0a49cadcb665"
      }
    },
    {
      "id": "502361fb-a5aa-46c4-a565-064b7bea2ba1",
      "name": "DFW - Home Loop 1 of 3",
      "description": "DFW residential streets, first part of leaving home making two stops and returning home. Starts at (-96.787513, 32.834516). Will leave a geofence at that location with a 50m radius in Z seconds.  Will enter a second geofence at (-96.783492, 32.834472) in Z seconds. Stops at (-96.783492, 32.834472).",
      "messageCount": 39,
      "locationCount": 39,
      "distanceByGPS": 381.036,
      "distanceByVSS": 383.402,
      "duration": 123626,
      "preview": "w~kgE|xvmQDUB}@A{@NiCQ{@BaAEk@@kAG}BDiAFm@AYCA",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/502361fb-a5aa-46c4-a565-064b7bea2ba1"
      }
    },
    {
      "id": "072ef6be-688c-4116-bbcf-dd046531b648",
      "name": "DFW - Home Loop 2 of 3",
      "description": "DFW residential streets, second part of leaving home making two stops and returning home. Starts at (-96.783491, 32.834459). Will leave a geofence at that location with a 50m radius in Z seconds.  Will enter a second geofence at (-96.786937, 32.831146) in Z seconds. Stops at (-96.786937, 32.831146).",
      "messageCount": 38,
      "locationCount": 38,
      "distanceByGPS": 702.972,
      "distanceByVSS": 701.821,
      "duration": 119370,
      "preview": "k~kgEx_vmQ`B[p@B^A^ElA?z@Gl@FZKl@NhA@r@Ed@?JLNf@IdJN~BDlAAbAC\\C@AD",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/072ef6be-688c-4116-bbcf-dd046531b648"
      }
    },
    {
      "id": "377d7edc-ba9f-4d4c-a898-7c955f8d4eb6",
      "name": "DFW - Home Loop 3 of 3",
      "description": "DFW residential streets, third part of leaving home making two stops and returning home. Starts at (-96.786936, 32.831146). Will leave a geofence at that location with a 50m radius.  Will enter a second geofence at (-96.787518, 32.83455). Stops at (-96.787518, 32.83455).",
      "messageCount": 23,
      "locationCount": 23,
      "distanceByGPS": 416.802,
      "distanceByVSS": 436.012,
      "duration": 73684,
      "preview": "uikgEjuvmQADmCBo@DWEKH[Ho@HiEGcA?w@F]AQBEn@BNAJ",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/377d7edc-ba9f-4d4c-a898-7c955f8d4eb6"
      }
    },
    {
      "id": "3914d927-efae-43e8-9a00-5bffb1cae110",
      "name": "LAS - CES 1",
      "description": "200 locations in Southeast Las Vegas",
      "messageCount": 200,
      "locationCount": 200,
      "distanceByGPS": 13165.6,
      "distanceByVSS": 8558.36,
      "duration": 600001,
      "preview": "ufs{E`ik}T?fZyUZoAEmAKoB[eC{@cB}@aBiAyByBmBqAeAk@_Aa@iA]cB]aBOaCE_m@|@Jnd@@bPHnRHlc@c@Kyj@He@HM`SLaSh@RbRGpW?b@SlFA\\EbAF|@LrAVfA`@fAj@vAfA`DpDfA~@xA|@fBj@rAVn@BxDB?tZMp@@p|@CzE\\q@x@gAzBoCfDwDrAgBrHsIly@_aA]k@XYmAiBM]Gc@EmAGw@?a\\BkSBq@^eBd@w@hFgH\\w@Rs@N{@H_AD}BHw[CkY}X@",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/3914d927-efae-43e8-9a00-5bffb1cae110"
      }
    },
    {
      "id": "170820b0-fc2d-4ee6-aacd-88011d542545",
      "name": "Med Route - DFW",
      "description": "Out and about in Dallas",
      "messageCount": 277,
      "locationCount": 260,
      "distanceByGPS": 9357.61,
      "distanceByVSS": 9596.56,
      "duration": 957793,
      "preview": "wyhgEdeimQxDnCpBfEUpATnB~CdFbAl@l@bBVpBXhBz@~At@jArBbC`AtA|@vAfKxSjCxDhLzKh@Vn@JhDfAnBx@dA\\~FfEtGjO~@xAdFzC`ApBzAtA|AnAfAdA~@hBn@dBv@vAjAj@bB^z@d@Pz@JPnB~Ap@Z^pBb@|@Vb@r@d@\\l@bA|At@f@fIlIz@`ArClDn@|@jEdEp@d@j@n@Fh@?~@BvAF|ABzEDdBZpF\\xILfFLzC?rBDxBNxBfAvFXzB`@lBVl@Nn@`@xAnAjCH^VRp@bA\\Td@z@^hAXNb@b@Vd@^Tv@tAxBvBn@b@Ph@PZlAjBb@\\`@Tj@ThB`B|AjAr@VxA|@lBvA`ElDp@|@QvBa@`Au@|@y@LQJSnAM\\YZc@Xc@d@o@\\_AnBCj@FdApAfAd@vAn@lHFfBV|AJzAEhAJe@E?BMHF`@nAXtAFhARdBb@zBnAfNH|ABlBTfBfAjBEjE?jBPjB`@|Ag@n@~@d@x@x@z@lAd@|@v@lBXfAqCxAiBvAIIVM@SAHJOBZEG@CBBW^{@j@_A[GQA@EAG@EI\\RXHEUEV?XFQHER@ROD?BJKF[H@BDAKA",
      "links": {
        "self": "https://dummies.vin.li/api/v1/routes/170820b0-fc2d-4ee6-aacd-88011d542545"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 9,
      "limit": 20,
      "offset": 0,
      "links": {
        "first": "https://dummies.vin.li/api/v1/routes?offset=0&limit=20",
        "last": "https://dummies.vin.li/api/v1/routes?offset=0&limit=20"
      }
    }
  }
}

Virtual Vinli Runs

You can send your Dummy Device on a Dummy Route by creating a Run.

Create a Run
Request
POST https://dummies.vin.li/api/v1/dummies/{dummy_Id}/runs
Content-Type: application/json
{
  "run": {
    "vin": "VVV12912912913456",
    "routeId": "8e90cf47-c6c1-486d-9ba8-194f569c7309"
  }
}
Parameters
  • vin - Required. A made up, 17 digit number that must start with ‘VV’
  • routeID - Required. A Dummy Route of your choice
  • repeat - Optional boolean. Defaults to false. If true, will automatically restart the run after completion. If false, will not automatically restart the run.
Response
Get Current Run
Request
GET https://dummies.vin.li/api/v1/dummies/{dummy_Id}/runs/_current
Content-Type: application/json
Response
Delete the Current Run
Request
DELETE https://dummies.vin.li/api/v1/dummies/{dummy_Id}/runs/_current
Content-Type: application/json

Run may take up to 1 minute to delete.