23. GPS Mileage Report

Returns a list of distances travelled by assets that meet the given filter restrictions. Data returned is similar to the GPS Mileage Report results returned on the website. When returning all assets, there are two formats for displaying the results: all assets combined into one result, or all assets listed separately (described more below under target).

23.1 Request Data

The following is a list of parameters that are required and optional for this request.

Required Information
Name	Description
action	showposition
operation	mileage
format	xml
fromdate	epoch time. Results will be from events that occurred during or after this time.
todate	epoch time. Results will be from events the occurred during or before this time.
Note:In future releases there may be a 15 day limit on the date selection.
Optional Information
target	Query for a specific asset and only return information for that asset. If specified a reqtype (request type) must be specified as well. Note: there are two ways to select results for all assets. The default way (using no target) returns a result for each asset separately.The second way (using a target of -1 and a reqtype of dbid) returns 1 result of all assets combined.
reqtype	Flag to identify the key being used to identify the asset. Acceptable values: `tag` Key is a Zonar RFID tag number. In version 2.X a type must also be specified. `exsid` Key is the external system id. `vin` Key is the Vehicle Identification Number (VIN). `dbid` Key is the internal database id number. This is the most reliable key to use. `fleet` Key is the asset fleet number. In version 2.X a type must also be specified.
type	When using reqtype of tag or fleet this must also be specified in version 2. In version 1.x type Standard (0) is assumed. See asset types for more details.
loilocation	Query for results that only occurred within a specific location of interest. Value must be a location of interest name. Note: loilocation and loicategory are mutually exclusive, only one or the other may be specified.
loicategory	Query for results that only occurred within locations of interest* belonging to a specific category. Value must be a location of interest category name. Note: loilocation and loicategory are mutually exclusive, only one or the other may be specified.

23.1A Specifying a Particular Asset (Asset Target)

The target parameter may be used to request data for a specific asset. If used the type of target must be specified as described above. When using Version 2.X if the target type is tag or fleet the asset type must also be specified. See asset types for more details.

23.2 Data Returned

The returned information is similar to the results of the GPS Mileage Report on the website:
DTD:
<!ELEMENT gpsmileagelist (assetdist*)> <!ATTLIST gpsmileagelist ver CDATA #REQUIRED> <!ATTLIST gpsmileagelist count CDATA #REQUIRED> <!ATTLIST gpsmileagelist total CDATA #REQUIRED> <!ATTLIST gpsmileagelist start CDATA #REQUIRED> <!ATTLIST gpsmileagelist end CDATA #REQUIRED> <!ATTLIST gpsmileagelist unit CDATA #REQUIRED> <!ELEMENT assetdist (loi*)> <!ATTLIST assetdist tag CDATA #REQUIRED> <!ATTLIST assetdist fleet CDATA #REQUIRED> <!ATTLIST assetdist type CDATA #REQUIRED> <!ATTLIST assetdist id CDATA #REQUIRED> <!ELEMENT loi (from, to, name, distance)> <!ELEMENT from (#PCDATA)> <!ELEMENT to (#PCDATA)> <!ELEMENT name (#PCDATA)> <!ELEMENT distance (#PCDATA)>

Reply Data

Name Description

version The version number of the OMI call and return data.

count The number of results returned.

total The sum of all distances returned.

start The request epoch time (fromdate).

end The request epoch time (todate).

unit The unit of measurement that the distances are returned in (e.g. Miles or Kilometers).

tag The Zonar RFID tag number assigned to the asset. Coupled with the Type, this is usually the means by which an asset is identified in an inspection. The combination of tag number and type must be unique for each asset. If all assets are specified, this will be zero.

fleet Fleet number. An arbitrary text string of up to 20 characters in length. If the asset is a vehicle this is intended to be the user assigned identification for the vehicle. This is usually labeled 'Asset No.' in the web interface. The combination of fleet number and type must be unique for each asset. All assets must have a fleet number. If all assets are specified, this will be "ALL".

type The asset type identifier. The combination of tag number and type or fleet number and type is used to uniquely identify the asset. Text, 32 characters maximum length. All assets have a type. If all assets are specified, this will be zero.

id (asset) The internal database identifier for the asset object. This is the primary means of identifying an asset and how the asset is linked to other objects. If all assets are specified, this will be zero.

from The epoch start time for the returned distance (may not be equal to start).

to The epoch end time for the returned distance (may not be equal to end).

name The distance travelled will be within a Location of Interest. This is the Location's name.

distance The distance travelled. unit will denote the measurement this value is in.

Note: When using target=-1&reqtype=dbid to get one summary entry containing data for the entire fleet, the asset fleet will be set to "ALL" and the asset identifiers will be 0.

Example Request:

http://development.zonarsystems.net/interface.php?action=showposition&operation=mileage&format=xml&fromdate=1151737200&todate=1154156340

Example Success Reply (XML):

<gpsmileagelist ver="1" count="1" total="6.800000" start="1151737200" end="1154156340" unit="Miles"> <assetdist tag="0" fleet="ALL" type="0" id="0"> <loi> <from>1152114831</from> <to>1153927247</to> <name>Zonar HQ</name> <distance>6.800000</distance> </loi> </assetdist> </gpsmileagelist>

*LOI means Location of Interest; called "Zone" in GPS tools and reports in Ground Traffic Control web application.

Reply Data
Name	Description
version	The version number of the OMI call and return data.
count	The number of results returned.
total	The sum of all distances returned.
start	The request epoch time (fromdate).
end	The request epoch time (todate).
unit	The unit of measurement that the distances are returned in (e.g. Miles or Kilometers).
tag	The Zonar RFID tag number assigned to the asset. Coupled with the Type, this is usually the means by which an asset is identified in an inspection. The combination of tag number and type must be unique for each asset. If all assets are specified, this will be zero.
fleet	Fleet number. An arbitrary text string of up to 20 characters in length. If the asset is a vehicle this is intended to be the user assigned identification for the vehicle. This is usually labeled 'Asset No.' in the web interface. The combination of fleet number and type must be unique for each asset. All assets must have a fleet number. If all assets are specified, this will be "ALL".
type	The asset type identifier. The combination of tag number and type or fleet number and type is used to uniquely identify the asset. Text, 32 characters maximum length. All assets have a type. If all assets are specified, this will be zero.
id (asset)	The internal database identifier for the asset object. This is the primary means of identifying an asset and how the asset is linked to other objects. If all assets are specified, this will be zero.
from	The epoch start time for the returned distance (may not be equal to start).
to	The epoch end time for the returned distance (may not be equal to end).
name	The distance travelled will be within a Location of Interest. This is the Location's name.
distance	The distance travelled. unit will denote the measurement this value is in.