Trips API
- Phil Windley
The Trips API provides queries and events for interacting with the services that comprise it.
Return Results
Where the Trips API returns trip data, there are two kinds, trip summaries and trip details. A trip summary contains the following data fields
| Name | Type | Description |
| id | Integer | The internal system identifier for this trip. |
| startTime | DateTime | The start time of the trip. |
| endTime | DateTime | The end time of the trip if the trip is not in progress. |
| interval | Integer | The number of seconds from the start to the end of the trip |
| mileage | Float | The distance traveled during the trip. |
| avgSpeed | Float | The distance divided by the interval, expressed in units/hour |
| startWaypoint | Waypoint | The starting location of the trip. |
| endWaypoint | Waypoint | The ending location of the trip if the trip is in not progress. |
Trip details also include a data element called data that is an array of waypoints for the trip. The size of the array is determined by the length of the trip.
DateTime is an ISO8901 formatted time.
Waypoint is a map with the following structure:
| Name | Type | Description |
|---|---|---|
| longitude | Real | The longitude of the waypoint |
| latitude | Real | The latitude of the waypoint |
Queries
The query domains for the Trips API are
| development | b16x18 |
|---|---|
| production | fuse_trips |
The production version is always pre-pended to the production query domain with a period, so for version 1 of the API would use v1_fuse_trips as the query domain. In this document we will use the production query domain without the version. See Fuse Base URLs for more information on how to turn the descriptions shown here into a query URL.
fuse_trips:trips([<id>]|[<limit>],[<offset>])
Query trips. All parameters are optional. With <id>, the detailed trip data for a specific trip is returned. Without <id>, summary data for all trips (paginated) is returned, starting with the latest. By default 10 trips are returned, you can change that by setting <limit>. By default the query begins at the most recent trip. You can change the offset by setting the <offset> parameter. If the <id> parameter is given, the <limit> and <offset> are ignored.
For example, to return the ten most recent trips, you would simply for the following:
fuse_trips:trips()
To return the data for last 25 trips:
fuse_trips:trips(limit=25)
fuse_trips:tripsByDate(<start>, <end>)
Query past trips for those between a start and end time. Summary trip data is returned. Times are expressed in ISO8901 format.
For example to find all the trips for June 2014 in the US Mountain time zone:
fuse_trips:tripsByDate(start="20140601T000000-0600", end="20140701T000000-0600")
fuse_trips:tripName(<start>, <end>)
Query for a trip name for the given start and end point. The <start> and <end> parameters are expressed as WayPoints. Trip names are stored with start and end points that have reduced precision (i.e. the waypoint includes an area of about 435 in diameter). They are queried after the given start and end point are reduced in precision as well.
Events
The following events are used defined for trips in the Fuse API.
fuse:new_trip
A new trip has been detected with the following attributes:
| Name | Type | Description |
|---|---|---|
| id | String | trip id number |
| startTime | DateTime | time trip started |
| endTime | DateTime | time trip ended |
| startWaypoint | Waypoint | latitude and longitude of start point |
| endWaypoint | Waypoint | latitude and longitude of end point |
| mileage | Real | total trip length |
| data | Waypoint array | detailed waypoint information for trip |
fuse:trip_meta_data
New trip meta data is available for a trip with the given id. The following attributes are included
| Name | Type | Description |
|---|---|---|
| id | String | trip id number |
| tripName | String | name for the trip |
| tripCategory | String | category for trip. Usually the IRS categories for mileage deduction |
Services
The following services operate in the Trip API
fuse_trips:save_trip
Selector:
select when fuse new_trip
Synopsis:
Saves a trip by ID and a trip summary by ID in the service's persistent storage (entity variable). Adds trip name to trip summary if one is found.
Trips with a total mileage less than 0.01 miles are not saved.
Raises:
none
fuse_trips:update_trip
Selector:
select when fuse trip_meta_data
Synopsis:
Updates the trip summary for a given ID with meta data with the name and category from the event attributes. The name is stored for use in automatically naming other trips.
Raises:
none