25.0 Export a Path

Exports a GPS path object for a specified target. Data returned as either standard KML log file or binary GPS log file.
Note: This operation is only supported in version 2.X.

25.1A Request Data - Log Version 2 (Single Asset)

Required Information
Name	Description
action	showposition
operation	path
format	kml or binary - binary is explained below
starttime	Unix epoch timestamp
endtime	Unix epoch timestamp
target	The asset to query. If specified a reqtype (request type) must be specified as well.
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. See asset types for more details. Acceptable values are Standard or Trailer
version	OMI protocol version - version 2 only
logvers	`2`
Optional Information
tstype	A flag to indicate what the starttime/endtime variables represent. Acceptable values are: `log` Timestamp is the log point time. Log points after the starttime/before the endtime will be returned. `load` Timestamp is the time the log point was added to the Zonar-Web system. Log points that were uploaded after the starttime/before the endtime will be returned If tstype is not specified, or is blank a value of '`log`' will be assumed.
revgeocode	A flag to indicate whether or not to reverse geocode the points returned. Acceptable values are: `true` `false` If revgeocode is not specified, or is blank a value of '`false`' will be assumed. Note: This is currently only applied to CSV exports.

25.1B Request Data - Log Version 3+

Required Information
Name	Description
action	showposition
operation	path
format	xml, json, csv, kml or binary - binary is explained below
version	OMI protocol version - version 2 only
logvers	The supported versions are: `3` - adds support for multiple assets in a single file and a checksum `3.1` - adds an odometer reading and asset exsid to the csv export `3.2` - adds fuel data, acceleromter and status information `3.3` - adds zone attribute to event element in XML `3.4` - adds exsid attribute to asset element in XML
starttime	Unix epoch timestamp
endtime	Unix epoch timestamp
Optional Information
If any optional information is omitted, all asset data for the given start/stop time period will be returned
target	The asset to query. If specified a reqtype (request type) must be specified as well.
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. See asset types for more details.
tstype	A flag to indicate what the starttime/endtime variables represent. Acceptable values are: `log` Timestamp is the log point time. Log points after the starttime/before the endtime will be returned. `load` Timestamp is the time the log point was added to the Zonar-Web system. Log points that were uploaded after the starttime/before the endtime will be returned If tstype is not specified, or is blank a value of '`log`' will be assumed.
tsformat	A parameter to indicate the format for timestamps in the XML output. Default value if none is passed is `iso8601` `iso8601` Timestamp is formatted according to iso8601 standards, yyyy-mm-dd hh:mm:ss-timezone `epoch` Timestamp is formatted as an epoch timestamp. Note: If tsformat is not specified then a value of `iso8601` will be assumed. Note: tsformat is only used with `format=xml`
revgeocode	A flag to indicate whether or not to reverse geocode the points returned. Acceptable values are: `true` `false` If revgeocode is not specified, or is blank a value of '`false`' will be assumed. Note: This is currently only applied to CSV exports.
location	Location to filter with. Text, the desired location name. If provided only positions data for assets assigned to that location will be returned.

Advanced Path Filtering

You can find additional information on filtering your path results here.

25.2 Data Returned

A standard KML log file, XML, CSV or binary GPS log file or error message.

25.2B Binary Returned data

A binary GPS log file consists of a single header(56 bytes) and subsequent position entries(28 bytes/ea).

Binary File Header Format

GPS Export Log File Header Format Version 3
Total size 56 bytes. All offsets and sizes in bytes.
Offset	Type	Size	Description
0 - 7	ASCII Text	8	`ZGPSEXPT` Identifies the file as a GPS export log file
8 - 11	Unsigned Integer	4	Version. Identifies the header and entry version. This layout must be maintained by all versions. Currently supported is 3.
12 - 19	ASCII Text	8	Account code, unused bytes are to be null.
20 - 23	Unsigned long	4	Extraction timestamp - this is when the request was made.
24 - 27	Unsigned long	4	Entry count - the number of log entries to follow
28 - 43	ASCII Text	16	Route identification - can be left NULL for now.
44 - 55	Empty	12	Padding so that the header is an even multiple of the entry size.
Total:		56

You may view the version 2 header format here

Position Entry Layout

The file header will be followed by a series of position log entries. Each one will contain a timestamp, position, speed, heading, accumulated distance and information as to why the entry was recorded.

GPS Log File Entry Format Version 3
Total size 28 bytes. All offsets and sizes in bytes
Offset	Type	Size	Description
0-3	Unsigned Long	4	Timestamp (Unix epoch)
4-7	Signed Integer	4	Latitude component (degrees / 10,000,000)
8-11	Signed Integer	4	Longitude component (degrees / 10,000,000)
12-13	Unsigned short	2	Speed (0.001 m/s)
14	Unsigned char	1	TBD
15	Unsigned char	1	TBD
16-17	Unsigned short	2	Heading (0.01 degrees)
18-21	Unsigned long	4	Accumulated distance (odometer). Meters
22 - 23	Unsigned short	2	Bit mask. See bitmap layout for details.
24 - 27	Unsigned long	4	Asset id. The database id for the asset this entry is associated with. Version 3 only.
Total:		28

You may view the version 2 position entry layout here

Note: The accumulated distance/odometer in the binary log file differs from that given in a KML file. The binary log file accumulates the distance/odometer for the life of the GPS product. The KML odometer reads 0 at the start of the requested KML file.

Bitmap Layout

The bitmap encodes input status, logging reason and various other pieces of information according to which bits are on.

Bit Mask Map
Bit	Meaning
0	Input 1 state
1	Input 2 state
2	Input 3 state
3	Input 4 state
4	Input 5 state
5	Input 1 state change
6	Input 2 state change
7	Input 3 state change
8	Input 4 state change
9	Input 5 state change
10	Motion stop / start
11	Panic button
12	Geofence enter / exit
13	Power on Bit will be set True for all log entries, until unit is shut down, Then it will be set False for exactly one entry. (Version 2 data only)
14	Cold start If the unit powers up after a hard shutdown the initial entry will be logged with this bit set to true, otherwise all entries false. (Version 2 data only)
15	Speed and odometer source. Value of 1 indicates the source is J3. Value of 0 indicates the source is the HDGPS.

Checksum Layout

Version 3 export files have a trailing checksum appended to them. This is a 4 byte unsigned long quantity containing a CRC32 checksum of all the preceding data, including the header. Example Implementation in ANSI C code

25.2C XML/JSON Returned data

Version 3

DTD:
<!ELEMENT pathevents (asset*)> <!ATTLIST pathevents ver CDATA #REQUIRED> <!ATTLIST pathevents assetcount CDATA #REQUIRED> <!ELEMENT asset (event*)> <!ATTLIST asset id CDATA #REQUIRED> <!ATTLIST asset eventcount CDATA #REQUIRED> <!ELEMENT event (#PCDATA)> <!ATTLIST event lat CDATA #REQUIRED> <!ATTLIST event long CDATA #REQUIRED> <!ATTLIST event time CDATA #REQUIRED> <!ATTLIST event speed CDATA #REQUIRED> <!ATTLIST event heading CDATA #REQUIRED> <!ATTLIST event reason CDATA #REQUIRED> <!ATTLIST event distance_traveled CDATA #REQUIRED> -- WITH JSON ADD: <!ATTLIST event odometer CDATA #REQUIRED> <!ATTLIST event loadts CDATA #REQUIRED>
Version 3.2 XML results
DTD:
<!ELEMENT pathevents (asset*)> <!ATTLIST pathevents ver CDATA #REQUIRED> <!ATTLIST pathevents assetcount CDATA #REQUIRED> <!ELEMENT asset (event*)> <!ATTLIST asset id CDATA #REQUIRED> <!ATTLIST asset eventcount CDATA #REQUIRED> <!ELEMENT event (#PCDATA)> <!ATTLIST event lat CDATA #REQUIRED> <!ATTLIST event long CDATA #REQUIRED> <!ATTLIST event time CDATA #REQUIRED> <!ATTLIST event speed CDATA #REQUIRED> <!ATTLIST event heading CDATA #REQUIRED> <!ATTLIST event reason CDATA #REQUIRED> <!ATTLIST event distance_traveled CDATA #REQUIRED> <!ATTLIST event odometer CDATA #REQUIRED> <!ATTLIST event loadts CDATA #REQUIRED> <!ATTLIST event accel CDATA #REQUIRED> <!ATTLIST event status CDATA #REQUIRED> <!ATTLIST event fuel_counter CDATA #REQUIRED> <!ATTLIST event fuel_units CDATA #REQUIRED>
Version 3.3 XML includes an additional attribute in the event element named zone

Version 3.4 XML includes an additional attribute in the asset element named exsid

Reason Codes

The reason attribute specifies one or more log reason codes as detailed below.

XML/JSON Reason Codes
Code	Meaning
0	Reserved and invalid.
1	Input 1 state change
2	Input 2 state change
3	Input 3 state change
4	Input 4 state change
5	Input 5 state change
6	Cold Start
7	Power Off
8	Geofence
9	Motion Stop
10	Motion Start
11	Standard Event
12	Power On

Example XML Request:
https://development.zonarsystems.net/interface.php?action=showposition&operation=path&format=xml&reqtype=dbid&version=2&logvers=3&count=150&poweron=1&bbox=-122.75848388671875,47.42018972705277,-121.94686889648438,47.6080148197327&starttime=1189321200&endtime=1189493940&target=191

Example JSON Request:
https://development.zonarsystems.net/interface.php?action=showposition&operation=path&format=json&reqtype=dbid&version=2&logvers=3&count=150&poweron=1&bbox=-122.75848388671875,47.42018972705277,-121.94686889648438,47.6080148197327&starttime=1189321200&endtime=1189493940&target=191

Example XML Request logvers=3.2:
https://development.zonarsystems.net/interface.php?action=showposition&operation=path&format=xml&starttime=1274710864&endtime=1274743009&target=8&reqtype=dbid&type=Standard&version=2&logvers=3.2

Example XML Success Reply

Example JSON Success Reply

Example logvers=3.2 XML Success Reply

Example logvers=3.3 XML Success Reply

Example logvers=3.4 XML Success Reply

25.2D CSV Returned data

CSV returns the following columns:

Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason, Distance Traveled(Miles), Lat, Lon, Zone, Address

Logvers 3.1
Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason, Distance Traveled(Miles), Lat, Lon, Zone, Accumulated distance (Odometer in meters), EXSID

Logvers 3.2
Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason, Distance Traveled(Miles), Lat, Lon, Zone, Fuel Counter, Acceleration, Status Mask, Address

Date is returned as YYYY-MM-DD.
Time is returned as HH:MM:SS in 24 hour format.
Log reason is returned as an English language string (eg 'Standard').

Example Request:
https://development.zonarsystems.net/interface.php?action=showposition&operation=path&format=csv&reqtype=dbid&version=2&logvers=3.1&count=150&poweron=1&bbox=-122.75848388671875,47.42018972705277,-121.94686889648438,47.6080148197327&starttime=1189321200&endtime=1189493940&target=191

Example CSV Success Reply