Trips API

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

NameTypeDescription
idIntegerThe internal system identifier for this trip.
startTimeDateTimeThe start time of the trip.
endTimeDateTimeThe end time of the trip if the trip is not in progress.
intervalIntegerThe number of seconds from the start to the end of the trip
mileageFloatThe distance traveled during the trip.
avgSpeedFloatThe distance divided by the interval, expressed in units/hour
startWaypointWaypointThe starting location of the trip.
endWaypointWaypoint  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:

NameTypeDescription
longitudeRealThe longitude of the waypoint
latitudeRealThe latitude of the waypoint

Queries

The query domains for the Trips API are

developmentb16x18
productionfuse_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:

NameTypeDescription
idStringtrip id number
startTimeDateTimetime trip started
endTimeDateTimetime trip ended
startWaypointWaypointlatitude and longitude of start point
endWaypointWaypointlatitude and longitude of end point
mileageReal

total trip length

dataWaypoint arraydetailed 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

NameTypeDescription
idStringtrip id number
tripNameStringname for the trip
tripCategoryStringcategory 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