Trip Related

A trip is created when a vehicle is understood to have one full cycle of ignition:on to ignition:off. In some vehicles, these signals must be inferred.

Trips are the most commonly used objects in the API. They contain a wealth of metadata about a vehicle's usage history and a user's behavior.

At present, one write is possible: adding a tag to a trip.

The mobile apps have a feature that allows combining of trips that happened within 15 minutes of each other. This merge is applied on the apps' frontend only and does not affect the REST objects, which would show the multiple 'segments' as distinct and unrelated entities.

Trips must have a minimum distance of 10 metres or they will be discarded as invalid.

Get a specific trip

Returns a Trip Object

Definition

GET /trip/{id}/

Query Parameters

None

Example Request

curl  "https://api.vehiclemind.com/trip/{id}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Sample Response

{
  "url": "https://api.vehiclemind.com/trip/T_5ecb5afa2422d3d8/",
  "id": "T_5ecb5afa2422d3d8",
  "driver": "https://api.vehiclemind.com/user/U_de0cf1b496008d9b/",
  "user": "https://api.vehiclemind.com/user/U_de0cf1b496008d9b/",
  "started_at": "2015-03-20T00:53:43.969000Z",
  "ended_at": "2015-03-20T01:43:36.738000Z",
  "distance_m": 16219.4,
  "duration_s": 2992.8,
  "vehicle": "https://api.vehiclemind.com/vehicle/C_9aa0f0e09383666c/",
  "start_location": {
    "lat": 33.95235,
    "lon": -118.38511,
    "accuracy_m": 3.9
  },
  "start_address": {
    "name": "5862 Arbor Vitae Street, Los Angeles, CA 90045, USA",
    "display_name": "Arbor Vitae St, LA, CA",
    "street_number": "5862",
    "street_name": "Arbor Vitae St",
    "city": "LA",
    "state": "CA",
    "country": "US"
  },
  "end_location": {
    "lat": 34.08308,
    "lon": -118.3659,
    "accuracy_m": 9
  },
  "end_address": {
    "name": "667 North Crescent Heights Boulevard, Los Angeles, CA 90048, USA",
    "display_name": "N Crescent Heights Blvd, LA, CA",
    "street_number": "667",
    "street_name": "N Crescent Heights Blvd",
    "city": "LA",
    "state": "CA",
    "country": "US"
  },
  "path": "_kfnE|aqqUAka@?aFBmDAuB}B?eN@wH@oL?iB@{@C[MUOOO}AcCaAsBUm@qD}LkEgOkBp@uAVsA?e@Ei@I{@WeBk@cBa@a@GmBGsBIkAEm@?}B?QLiECeDBcTAeC?cB@OKyA?yF?wD?qBD_FLyK\\sTr@uBByACyAM}@MkAYo@QeGuBQM{Ai@qBq@uCs@gB[oBQ{BEeD?_CJ{K|@_Ff@mAXuBx@mVdLaGfDyBl@_BT}DVkDPsCHwVi@aBB_AH}AZoBn@mFdBgBTm@DsA@m@AoAOiAUmA_@oHeDuBy@iAWcAMoAEqCCG?QH_BCuFKgHUgIMaEM_KQcGKo@Wc@E{@QyBi@_IoCuJkDgEuA_Cy@{CcAm@M_@IeBEoBRiA\\kB|@iDhBk@R}@Tu@DoA?UCgBk@{Bw@mCw@_Bo@eIgCcD}@sHwAaNaCeEs@sA@mBEgASgOmFeLcEgFgBgBs@qMmF{DcBeBs@qAc@[E}B?eACuI?eD?KjB{@fPaDYyE]_@Ao@Fe@PuDzBeC~Aq@Vi@Hm@BqD?_RHoC?w_@AmHB",
  "fuel_cost_usd": 1.92,
  "fuel_volume_l": 2.1,
  "average_kmpl": 7.7,
  "average_from_epa_kmpl": 9.4,
  "score_events": 47.7,
  "score_speeding": 50,
  "hard_brakes": 0,
  "hard_accels": 1,
  "duration_over_70_s": 0,
  "duration_over_75_s": 0,
  "duration_over_80_s": 0,
  "vehicle_events": [
    {
      "type": "hard_accel",
      "lat": 33.97642,
      "lon": -118.37013,
      "created_at": "2015-03-20T01:06:36.547000Z",
      "g_force": 0.3374651
    }
  ],
  "start_timezone": "America/Los_Angeles",
  "end_timezone": "America/Los_Angeles",
  "city_fraction": 1,
  "highway_fraction": 0,
  "night_driving_fraction": 0,
  "idling_time_s": 37,
  "tags": [
    "business"
  ]
}

Note on Fuel cost

Fuel cost of a trip is based on the best fuel price information we have for a vehicle at the time of the trip, including the fuel grade selected by a user preference.

In the United States, fuel price is retrieved automatically based on location at the time of fillup. If a car does not report its fuel level, then each trip's cost will be estimated using prevailing local prices.

Outside the United States, our fuel costing will currently provide unreliable results. This will be improved in the future. For the time being, it is recommended to use fuel volume as the reliable metric instead.

Note on Path Data

Trip paths are stored in a format called Encoded Polyline. Polyline is a small javascript library that can encode and decode this data into an array of lat/long points. Alternatively, you can use this web-based utility to do this manually. If building an application using Google Maps, you can use encoded polylines natively without conversion.

In cases where no GPS signal was available during the trip, path may be returned as null.

NOTE:score_events andscore_speeding are not fully implemented as of the time of this writing. Trips will return without those fields until it is implemented

Get a list of trips

Returns an array of Trip Objects.

Provides a listing of trips matching the query parameters.

Definition

GET /trip/

Query Parameters

Parameter Description
started_at_lte
Optional, default is null
(INTEGER) Start time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8" = 1431126000
started_at_gte
Optional, default is null
(INTEGER) Start time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
ended_at_lte
Optional, default is null
(INTEGER) End time (<=) filter in seconds since epoch time. e.g. "2015-may-9 16:00 gmt-8" = 1431126000
ended_at_gte
Optional, default is null
(INTEGER) End time (>=) filter in seconds since epoch time. e.g. "2015-May-9 16:00 GMT-8" = 1431126000
vehicle
Optional, default is null
(STRING) Vehicle Filter
tags_in
Optional, default is null
(STRING) Tags Filter
page
Optional, default is 1
(INTEGER) Specifies the page of paginated results to return.
limit
Optional, default is 10, max is 250. Though accounts have lower limits on vehicles that can be attached to an account.
(INTEGER) Number of results per page

Example Request

This query will look for trips that happened between Jan 1 and Feb 1, 2015 in a specific vehicle and with the business tag, returning 5 per page.

curl "https://api.vehiclemind.com/trip/?started_at_gte=1426898108&ended_at_lte=1426916941&vehicle=C_9aa0f0e09383666c&tags_in=business&limit=5" \
-H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Sample Response

{
  "_metadata": {
    "count": 5,
    "next": "https://api.vehiclemind.com/trip/?limit=1&page=2",
    "previous": null
  },
  "results": [
    {
      "url": "https://api.vehiclemind.com/trip/T_5ecb5afa2422d3d8/",
      "id": "T_5ecb5afa2422d3d8",
      "driver": "https://api.vehiclemind.com/user/U_de0cf1b496008d9b/",
      "user": "https://api.vehiclemind.com/user/U_de0cf1b496008d9b/",
      "started_at": "2015-03-20T00:53:43.969000Z",
      "ended_at": "2015-03-20T01:43:36.738000Z",
      "distance_m": 16219.4,
      "duration_s": 2992.8,
      "vehicle": "https://api.vehiclemind.com/vehicle/C_9aa0f0e09383666c/",
      "start_location": {
        "lat": 33.95235,
        "lon": -118.38511,
        "accuracy_m": 3.9
      },
      "start_address": {
        "name": "5862 Arbor Vitae Street, Los Angeles, CA 90045, USA",
        "display_name": "Arbor Vitae St, LA, CA",
        "street_number": "5862",
        "street_name": "Arbor Vitae St",
        "city": "LA",
        "state": "CA",
        "country": "US"
      },
      "end_location": {
        "lat": 34.08308,
        "lon": -118.3659,
        "accuracy_m": 9
      },
      "end_address": {
        "name": "667 North Crescent Heights Boulevard, Los Angeles, CA 90048, USA",
        "display_name": "N Crescent Heights Blvd, LA, CA",
        "street_number": "667",
        "street_name": "N Crescent Heights Blvd",
        "city": "LA",
        "state": "CA",
        "country": "US"
      },
      "path": "_kfnE|aqqUAka@?aFBmDAuB}B?eN@wH@oL?iB@{@C[MUOOO}AcCaAsBUm@qD}LkEgOkBp@uAVsA?e@Ei@I{@WeBk@cBa@a@GmBGsBIkAEm@?}B?QLiECeDBcTAeC?cB@OKyA?yF?wD?qBD_FLyK\\sTr@uBByACyAM}@MkAYo@QeGuBQM{Ai@qBq@uCs@gB[oBQ{BEeD?_CJ{K|@_Ff@mAXuBx@mVdLaGfDyBl@_BT}DVkDPsCHwVi@aBB_AH}AZoBn@mFdBgBTm@DsA@m@AoAOiAUmA_@oHeDuBy@iAWcAMoAEqCCG?QH_BCuFKgHUgIMaEM_KQcGKo@Wc@E{@QyBi@_IoCuJkDgEuA_Cy@{CcAm@M_@IeBEoBRiA\\kB|@iDhBk@R}@Tu@DoA?UCgBk@{Bw@mCw@_Bo@eIgCcD}@sHwAaNaCeEs@sA@mBEgASgOmFeLcEgFgBgBs@qMmF{DcBeBs@qAc@[E}B?eACuI?eD?KjB{@fPaDYyE]_@Ao@Fe@PuDzBeC~Aq@Vi@Hm@BqD?_RHoC?w_@AmHB",
      "fuel_cost_usd": 1.92,
      "fuel_volume_l": 2.1,
      "average_kmpl": 7.7,
      "average_from_epa_kmpl": 9.4,
      "score_events": 47.7,
      "score_speeding": 50,
      "hard_brakes": 0,
      "hard_accels": 1,
      "duration_over_70_s": 0,
      "duration_over_75_s": 0,
      "duration_over_80_s": 0,
      "vehicle_events": [
        {
          "type": "hard_accel",
          "lat": 33.97642,
          "lon": -118.37013,
          "created_at": "2015-03-20T01:06:36.547000Z",
          "g_force": 0.3374651
        }
      ],
      "start_timezone": "America/Los_Angeles",
      "end_timezone": "America/Los_Angeles",
      "city_fraction": 1,
      "highway_fraction": 0,
      "night_driving_fraction": 0,
      "idling_time_s": 37,
      "tags": [
        "business"
      ]
    }
  ]
}

Remove tag from a trip

Returns a TripTag Object.

Removes a TripTag from a Trip.

Definition

DELETE /trip/{trip_id}/tag/{tag}/

Query Parameters

None

Example Request

curl -X DELETE "https://api.vehiclemind.com/trip/{trip_id}/tag/{tag}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Sample Response

{}

Get a tag associated with trip

Returns a TripTag Object.

Returns a specific TripTag, which is the association of a Tag to a trip. Whereas the Tags are available as an array in a Trip, calling the specific TripTag object additionally provides the time a given tag was applied to a trip.

Definition

GET /trip/{trip_id}/tag/{tag}/

Query Parameters

None

Example Request

curl  "https://api.vehiclemind.com/trip/{trip_id}/tag/{tag}/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991"

Sample Response

{
  "tag": "business",
  "created_at": "2015-03-19T21:39:49.333000Z"
}

Tag a trip

Returns a TripTagCreate Object.

Creates a TripTag to apply a Tag to a Trip.

Definition

POST /trip/{trip_id}/tag/

Query Parameters

None

Example Request

curl -X POST "https://api.vehiclemind.com/trip/{trip_id}/tag/" \
  -H "Authorization:Bearer e5cdd2a2f2c52ac2ff9825f53ac566f45c513991" \
  -d tag="personal"

Sample Response

{
  "tag": "personal",
  "created_at": "2015-03-19T21:39:49"
}