Use this call to export a GPS path object for a specified target. Data is returned as either standard KML log file or binary GPS log file.
Request Data
Note: This operation is only supported in version 2.X.
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:
|
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 | API protocol version - version 2 only |
logvers | 2 |
Optional Information | |
tstype | A flag to indicate what the starttime/endtime variables represent. Acceptable values are:
log ' will be assumed. |
revgeocode | A flag to indicate whether or not to reverse geocode the points returned. Acceptable values are:
false ' will be assumed.
Note: This is currently only applied to CSV exports. |
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 | API protocol version - version 2 only |
logvers | The supported versions are:
|
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:
|
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 ' will be assumed. |
tsformat | A parameter to indicate the format for timestamps in the XML output. Default value if none is passed is iso8601
Note: If tsformat is not specified then a value of Note: tsformat is only used with |
revgeocode | A flag to indicate whether or not to reverse geocode the points returned. Acceptable values are:
false ' will be assumed.
Note: This is currently only applied to CSV exports. (Also in XML with logvers 3.8) |
location | Location to filter with. Text, the desired location name. If provided only positions data for assets assigned to that location will be returned.
You can find additional information on filtering your path results here. |
Advanced Path Options
This section explains the more advanced options for filtering path information.
Name | Description | |
---|---|---|
bbox | A bounding box used to limit results. The format is as follows: lon1, lat1, lon2, lat2 Where lat1, lon1 is the upper left corner of the box and lat2, lon2 is the lower right corner. |
|
GPS Point Flags | ||
standard | A flag to indicate if you want to see standard gps points in your return data. Acceptable values are:
|
|
sc1 | A flag to indicate if you want to see state change for input 1 gps points in your return data. Acceptable values are:
|
|
sc2 | A flag to indicate if you want to see state change for input 2 gps points in your return data. Acceptable values are:
|
|
sc3 | A flag to indicate if you want to see state change for input 3 gps points in your return data. Acceptable values are:
|
|
sc4 | A flag to indicate if you want to see state change for input 4 gps points in your return data. Acceptable values are:
|
|
sc5 | A flag to indicate if you want to see state change for input 5 gps points in your return data. Acceptable values are:
|
|
motionstart | A flag to indicate if you want to see motion start gps points in your return data. Acceptable values are:
Note: If no value is passed for any of the GPS point flags, a value of 1 is assumed for all. If a value is passed for any of them, then the default value for any unspecified flags is treated as 0. |
|
motionstop | A flag to indicate if you want to see motion stop gps points in your return data. Acceptable values are:
|
|
panic | A flag to indicate if you want to see panic gps points in your return data. Acceptable values are:
|
|
fence | A flag to indicate if you want to see geofence gps points in your return data. Acceptable values are:
|
|
coldstart | A flag to indicate if you want to see coldstart gps points in your return data. Acceptable values are:
|
|
poweron | A flag to indicate if you want to see poweron gps points in your return data. Acceptable values are:
|
|
poweroff | A flag to indicate if you want to see poweroff gps points in your return data. Acceptable values are:
|
Reason Codes
The reason attribute specifies one or more log reason codes as detailed below.
The flags listed above for GPS points correspond to the following reason codes in the returned data. For example if you specify poweron=1
and no other GPS flags you will only receive GPS points with a reason of 12 (Power on). Some points have multiple reasons, if any of the reasons is 12 eg. reason="6,12"
you will receive them as well.
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://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=path&reqtype=dbid&target=191&version=2&starttime=1189321200&endtime=1189493940&logvers=3&format=xml
Example JSON Request
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition
&operation=path&reqtype=dbid&target=191&version=2&starttime=1189321200
&endtime=1189493940&logvers=3&format=json
Example XML Request logvers=3.2
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition
&operation=path&reqtype=dbid&target=8&type=Standard&version=2&starttime=1274710864
&endtime=1274743009&logvers=3.2&format=xml
Data Returned
A standard KML log file, XML, CSV or binary GPS log file or error message.
KML Data Returned
Keyhole Markup Language (KML) is a standard XML file used for storing geographic data for display in Google Earth. A full specification and related information can be obtained from Google Earth KML 2.0.
Information about the KML file can be found in the "Document" element.
DTD
<!ELEMENT Document (#PCDATA | name | description | Style | Folder)*>
<!ELEMENT timePosition (#PCDATA)>
<!ELEMENT styleUrl (#PCDATA)>
<!ELEMENT width (#PCDATA)>
<!ELEMENT LineStyle (#PCDATA | color | width)*>
<!ELEMENT Style (#PCDATA | IconStyle | LineStyle)*>
<!ATTLIST Style id CDATA #IMPLIED>
<!ELEMENT href (#PCDATA)>
<!ELEMENT w (#PCDATA)>
<!ELEMENT h (#PCDATA)>
<!ELEMENT Icon (#PCDATA | href | y | w | h | x)*>
<!ELEMENT MultiGeometry (#PCDATA | LineString)*>
<!ELEMENT TimeInstant (#PCDATA | timePosition)*>
<!ELEMENT color (#PCDATA)>
<!ELEMENT kml (#PCDATA | Document)*>
<!ELEMENT Point (#PCDATA | coordinates)*>
<!ELEMENT description (#PCDATA)>
<!ELEMENT IconStyle (#PCDATA | Icon)*>
<!ELEMENT y (#PCDATA)>
<!ELEMENT Folder (#PCDATA | name | Placemark | Folder | description)*>
<!ELEMENT LineString (#PCDATA | coordinates)*>
<!ELEMENT name (#PCDATA)>
<!ELEMENT x (#PCDATA)>
<!ELEMENT coordinates (#PCDATA)>
<!ELEMENT Placemark (#PCDATA | name | styleUrl | MultiGeometry | description | TimeInstant | Point)*>
Binary Data Returned
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 Log Versions 2 and 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 |
GPS Export Log File Header Format Version 3.2 | |||
---|---|---|---|
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 |
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 |
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.
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.
XML/JSON Data Returned
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
Version 3.6 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 reasons 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>
<!ATTLIST event address CDATA #REQUIRED>
<!ATTLIST event zone CDATA #REQUIRED>
<!ATTLIST event air_temp CDATA #REQUIRED>
<!ATTLIST event avg_rpm CDATA #REQUIRED>
<!ATTLIST event avg_load CDATA #REQUIRED>
<!ATTLIST event outside_pressure CDATA #REQUIRED>
<!ATTLIST event peak_rpm CDATA #REQUIRED>
<!ATTLIST event average_torque CDATA #REQUIRED>
<!ATTLIST event boost_pressure CDATA #REQUIRED>
<!ATTLIST event ffilter_dpressure CDATA #REQUIRED>
<!ATTLIST event afilter_dpressure CDATA #REQUIRED>
<!ATTLIST event dpf_dpressure CDATA #REQUIRED>
<!ATTLIST event regen_status CDATA #REQUIRED>
Version 3.7 XML is the same as version 3.6
Version 3.8 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 reasons 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>
<!ATTLIST event address CDATA #REQUIRED>
<!ATTLIST event source CDATA #REQUIRED>
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 |
13 | Panic - only with logvers 3.8 |
Regen Status Bitmask
For information on how to interpret bitmask values, see Status Mask.
Bit | Description |
0 | Regening |
1 | Forced Regen |
2 | Regen Inhibited |
3 | Manual Inhibit |
4 | Clutch Inhibit |
5 | Brake (Service) Inhibit |
6 | Brake (Parking) Inhibit |
7 | PTO Inhibit |
8 | Throttle Pedal Inhibit |
9 | Neutral Switch Inhibit |
10 | Vehicle Speed (High) Inhibit |
11 | Vehicle Speed (Low) Inhibit |
12 | Exhaust Gas Temp Inhibit |
13 | Engine Temp (Low) Inhibit |
14 | Other System Inhibit |
Example XML Success Reply
<pathevents ver="3" assetcount="2">
<asset id="310" eventcount="4">
<event lat="26.106157" long="-80.259347" time="2009-07-23 11:14:03-07" speed="0.0" heading="N" reasons="6,12,9" distance_traveled="0" odometer="209.2" loadts="2009-07-23 11:21:01.708821-07"/>
<event lat="26.106193" long="-80.259270" time="2009-07-23 11:36:45-07" speed="0.0" heading="N" reasons="12,9" distance_traveled="0" odometer="209.2" loadts="2009-07-23 11:36:49.265859-07"/>
<event lat="26.106189" long="-80.259282" time="2009-07-23 11:43:04-07" speed="0.0" heading="N" reasons="12,9" distance_traveled="0" odometer="209.2" loadts="2009-07-23 11:45:51.421893-07"/>
<event lat="26.106154" long="-80.259297" time="2009-07-23 11:45:24-07" speed="9.5" heading="W" reasons="12,10" distance_traveled="0" odometer="209.2" loadts="2009-07-23 11:45:51.421893-07"/>
</asset>
<asset id="466" eventcount="2">
<event lat="47.437398" long="-122.247567" time="2009-07-23 16:01:57-07" speed="0.0" heading="SSW" reasons="6,12,9" distance_traveled="8" odometer="1127.5" loadts="2009-07-30 11:18:00.275462-07"/>
<event lat="47.437455" long="-122.247709" time="2009-07-23 16:13:15-07" speed="0.1" heading="S" reasons="12,10" distance_traveled="8" odometer="1127.5" loadts="2009-07-30 11:18:00.275462-07"/>
</asset>
</pathevents>
Example JSON Success Reply
{
"pathevents": {
"ver": 3,
"assetcount": 2,
"assets": [
{
"id": 310,
"eventcount": 4,
"events": [
{
"lat": 26.1061566,
"lng": -80.2593472,
"time": "2009-07-23 11:14:03-07",
"speed": "0.0",
"heading": "N",
"reasons": "6,12,9",
"distance_traveled": 0,
"odometer": 209.2,
"loadts": "2009-07-23 11:21:01.708821-07"
},
{
"lat": 26.1061934,
"lng": -80.2592703,
"time": "2009-07-23 11:36:45-07",
"speed": "0.0",
"heading": "N",
"reasons": "12,9",
"distance_traveled": 0,
"odometer": 209.2,
"loadts": "2009-07-23 11:36:49.265859-07"
},
{
"lat": 26.1061886,
"lng": -80.2592818,
"time": "2009-07-23 11:43:04-07",
"speed": "0.0",
"heading": "N",
"reasons": "12,9",
"distance_traveled": 0,
"odometer": 209.2,
"loadts": "2009-07-23 11:45:51.421893-07"
},
{
"lat": 26.106154,
"lng": -80.2592971,
"time": "2009-07-23 11:45:24-07",
"speed": "9.5",
"heading": "W",
"reasons": "12,10",
"distance_traveled": 0,
"odometer": 209.2,
"loadts": "2009-07-23 11:45:51.421893-07"
}
]
},
{
"id": 466,
"eventcount": 2,
"events": [
{
"lat": 47.4373983,
"lng": -122.2475671,
"time": "2009-07-23 16:01:57-07",
"speed": "0.0",
"heading": "SSW",
"reasons": "6,12,9",
"distance_traveled": 8,
"odometer": 1127.5,
"loadts": "2009-07-30 11:18:00.275462-07"
},
{
"lat": 47.4374547,
"lng": -122.2477094,
"time": "2009-07-23 16:13:15-07",
"speed": "0.1",
"heading": "S",
"reasons": "12,10",
"distance_traveled": 8,
"odometer": 1127.5,
"loadts": "2009-07-30 11:18:00.275462-07"
}
]
}
]
}
}
CSV Data Returned
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
Logvers 3.3 CSV is the same as logversion 3.2
Logvers 3.5
Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason,
Distance Traveled(Miles), Lat, Lon, Zone, Fuel Counter(Gallon),
Acceleration(Miles/Hour/Sec), Status Mask, Address
Logvers 3.6
Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason,
Distance Traveled(Miles), Lat, Lon, Zone, Address, Odometer, EXSID,
Acceleration(Miles/Hour/Sec), Status Mask, Fuel Counter(Gallon), Air Temperature,
Average RPM, Average Load, Outside Pressure, Peak RPM, Average Torque, Boost Pressure,
FFilter Dpressure, AFilter Dpressure, DFP Dpressure, Regen Status
Logvers 3.7 CSV is the same as logversion 3.6
Logvers 3.8
Asset ID, Asset No., Date, Time(PDT), Speed(MPH), Heading, Log Reason,
Distance Traveled(Miles), Lat, Lon, Zone, Address, Source
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://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition
&operation=path&reqtype=dbid&target=191&version=2&starttime=1189321200
&endtime=1189493940&logvers=3.1&format=csv