Use this call to export the last location of one or more assets. Data is returned as a standard Keyhole Markup Language (KML) log file, XML, or a version 3 GPS log file.
Note: Only log version 3 is supported for binary current location requests. Log version 3.1 adds an odometer value in XML format only.
Request Data
The following are parameters that are required and optional for these requests.
Required Information | |
---|---|
Name | Description |
action | showposition |
operation | current |
format | xml, kml or binary - binary is explained below |
version | API protocol version - version 2 only |
logvers |
|
Optional Information | |
target | Identifies one particular asset according to reqtype. |
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. In version 1.x type Standard (0) is assumed. See asset types for more details. |
count | The maximum number of results to return.
Note: Only valid for xml and kml |
sortfield | Field to sort results by. Acceptable values:
Note: Only valid for xml and kml |
sortdir | Direction results are to be sorted by. Acceptable values:
Note: Only valid for xml and kml |
startrow | Can be used in combination with count to limit results to a subset. The subset will start at startrow and end at count.
Note: Only valid for xml and kml |
power | Filter results with power flag. Acceptable values:
Note: Only valid for xml and kml |
loilocation | A LOI1 name. If supplied, the distance from the asset to the center of this LOI is returned. |
loifilter | An LOI1 ID. If supplied, only assets within this LOI are returned. |
loicatfilter | An LOI1 Category ID. If supplied, only assets within this LOIs in this category are returned. |
include_loi | An LOI1 Set to '1' to include the smallest GPS Zone (LOI) the asset is current in. |
locname | Filter by name of the location associated with the asset. If not used, all asset locations will be returned. |
ztrak | Indicates whether ZTrack units are returned by the current location request. Boolean data type with only two possible values: true or false. |
1 LOI means Location of Interest; called "Zone" in the GPS tools and reports found within the Ground Traffic Control web application.
Data Returned
Data returned is XML, a standard KML log file, a binary version 3 GPS log file, or an XML error message.
XML Data Returned
The current location(s) for the specified assets (all if none specified) are returned in XML format.
DTD
<!ELEMENT currentlocation (asset*)>
<!ELEMENT asset (long, lat, heading, time, speed, power, loi_distance)> <!ATTLIST asset tagid CDATA #REQUIRED> <!ATTLIST asset fleet CDATA #REQUIRED> <!ATTLIST asset id CDATA #REQUIRED> <!ATTLIST asset type CDATA #REQUIRED>
<!ELEMENT long (#PCDATA)> <!ELEMENT lat (#PCDATA)> <!ELEMENT loi (#PCDATA)> <!ELEMENT heading (#PCDATA)> <!ELEMENT time (#PCDATA)> <!ELEMENT speed (#PCDATA)> <!ATTLIST speed unit CDATA #REQUIRED> <!ELEMENT power (#PCDATA)> <!ELEMENT loi_distance (#PCDATA)> <!ATTLIST loi_distance name CDATA #REQUIRED> <!ATTLIST loi_distance unit CDATA #REQUIRED> <!ATTLIST loi_distance inside CDATA #REQUIRED>
DTD for logvers=3.1
<!ELEMENT currentlocation (asset*)>
<!ELEMENT asset (long, lat, heading, time, speed, power, loi_distance)> <!ATTLIST asset tagid CDATA #REQUIRED> <!ATTLIST asset fleet CDATA #REQUIRED> <!ATTLIST asset id CDATA #REQUIRED> <!ATTLIST asset type CDATA #REQUIRED>
<!ELEMENT long (#PCDATA)> <!ELEMENT lat (#PCDATA)> <!ELEMENT loi (#PCDATA)> <!ELEMENT heading (#PCDATA)> <!ELEMENT time (#PCDATA)> <!ELEMENT speed (#PCDATA)> <!ATTLIST speed unit CDATA #REQUIRED> <!ELEMENT power (#PCDATA)> <!ELEMENT loi_distance (#PCDATA)> <!ATTLIST loi_distance name CDATA #REQUIRED> <!ATTLIST loi_distance unit CDATA #REQUIRED> <!ATTLIST loi_distance inside CDATA #REQUIRED> <!ELEMENT odometer (#PCDATA)>
DTD for logvers=3.4
<!ELEMENT currentlocation (asset*)>
<!ELEMENT asset (long, lat, heading, time, speed, power, loi_distance>
<!ATTLIST asset tagid CDATA #REQUIRED>
<!ATTLIST asset fleet CDATA #REQUIRED>
<!ATTLIST asset id CDATA #REQUIRED>
<!ATTLIST asset type CDATA #REQUIRED>
<!ATTLIST asset exsid CDATA #REQUIRED>
<!ELEMENT long (#PCDATA)>
<!ELEMENT lat (#PCDATA)>
<!ELEMENT loi (#PCDATA)>
<!ELEMENT heading (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT speed (#PCDATA)>
<!ATTLIST speed unit CDATA #REQUIRED>
<!ELEMENT power (#PCDATA)>
<!ELEMENT loi_distance (#PCDATA)>
<!ATTLIST loi_distance name CDATA #REQUIRED>
<!ATTLIST loi_distance unit CDATA #REQUIRED>
<!ATTLIST loi_distance inside CDATA #REQUIRED>
<!ELEMENT address (#PCDATA)>
DTD for logvers=3.5
<!ELEMENT currentlocation (asset*)>
<!ELEMENT asset (long, lat, heading, time, speed, power, loi_distance)>
<!ATTLIST asset tagid CDATA #REQUIRED>
<!ATTLIST asset fleet CDATA #REQUIRED>
<!ATTLIST asset id CDATA #REQUIRED>
<!ATTLIST asset type CDATA #REQUIRED>
<!ELEMENT long (#PCDATA)>
<!ELEMENT lat (#PCDATA)>
<!ELEMENT loi (#PCDATA)>
<!ELEMENT heading (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT speed (#PCDATA)>
<!ATTLIST speed unit CDATA #REQUIRED>
<!ELEMENT power (#PCDATA)>
<!ELEMENT odometer (#PCDATA)>
<!ELEMENT odo_offset (#PCDATA)>
<!ELEMENT source (#PCDATA)>
<!ELEMENT fuel_counter (#PCDATA)>
<!ATTLIST fuel_counter unit CDATA #REQUIRED>
<!ELEMENT fuel_level_pct (#PCDATA)>
<!ELEMENT fuel_counter (#PCDATA)>
<!ELEMENT avg_rpm (#PCDATA)>
<!ATTLIST loi_distance name CDATA #REQUIRED>
<!ATTLIST loi_distance unit CDATA #REQUIRED>
<!ATTLIST loi_distance inside CDATA #REQUIRED>
DTD for logvers=3.6
<!ELEMENT currentlocation (asset*)>
<!ELEMENT asset (long, lat, heading, time, speed, power, loi_distance)>
<!ATTLIST asset tagid CDATA #REQUIRED>
<!ATTLIST asset fleet CDATA #REQUIRED>
<!ATTLIST asset id CDATA #REQUIRED>
<!ATTLIST asset type CDATA #REQUIRED>
<!ELEMENT long (#PCDATA)>
<!ELEMENT lat (#PCDATA)>
<!ELEMENT loi (#PCDATA)>
<!ELEMENT heading (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT speed (#PCDATA)>
<!ATTLIST speed unit CDATA #REQUIRED>
<!ELEMENT power (#PCDATA)>
<!ELEMENT odometer (#PCDATA)>
<!ELEMENT odo_offset (#PCDATA)>
<!ELEMENT source (#PCDATA)>
<!ELEMENT fuel_counter (#PCDATA)>
<!ATTLIST fuel_counter unit CDATA #REQUIRED>
<!ELEMENT fuel_level_pct (#PCDATA)>
<!ELEMENT fuel_counter (#PCDATA)>
<!ELEMENT avg_rpm (#PCDATA)>
<!ATTLIST loi_distance name CDATA #REQUIRED>
<!ATTLIST loi_distance unit CDATA #REQUIRED>
<!ATTLIST loi_distance inside CDATA #REQUIRED>
<!ELEMENT address (#PCDATA)>
Reply Data | |
---|---|
Name | Description |
tagid | The Zonar RFID tag number assigned to the asset. |
fleet | Fleet number. An arbitrary text string of up to 20 characters in length. |
type | The asset type identifier. |
long | the longitude of the last location |
lat | the latitude of the last location |
time | the timestamp of the last reported location |
heading | the heading at the last location. |
speed | the speed at the last location |
unit(speed) | the units associated with the speed value |
power | the status of the power flag. |
loi_distance | the distance from the asset to the center of the LOI (if supplied). |
name (loi_distance) | name of the queried LOI |
unit (loi_distance) | the unit associated with the LOI1 distance |
inside (loi_distance) | 0 or 1 to indicate the asset is outside or inside the LOI respectively |
odometer | Odometer value measured in meters. |
odo_offset | Odometer offset value measured in meters. |
address | Geocoded Address based on lat/long. |
source | Data source (GPS or ECM). |
fuel_counter | Fuel counter at the last location. |
unit(fuel_counter) | The unit associated with the fuel counter. |
fuel_level_pct | Fuel level percentage at the last location. |
avg_rpm | Average RPM between the last location and the GPS point before it. |
1 LOI means Location of Interest; called "Zone" in the GPS tools and reports found within the Ground Traffic Control web application.
Example XML Request (single asset)
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&target=182&reqtype=dbid
Example Success Reply XML
<?xml version="1.0"?>
<currentlocations>
<asset tagid="" fleet="GSM_8306_Ryan" id="182" type="0">
<long>47.4276639</long>
<lat>-122.2940209</lat>
<heading>358.290000</heading>
<time>2007-05-23 14:14 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>on</power>
</asset>
</currentlocations>
Example XML Request (single asset, with location)
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&target=182&reqtype=dbid&loilocation=AcmeHQ
Example Success Reply XML
<?xml version="1.0"?>
<currentlocations>
<asset tagid="" fleet="GSM_8306_Ryan" id="182" type="0">
<long>-122.2940209</long>
<lat>47.4276639</lat>
<heading>358.290000</heading>
<time>2007-05-23 14:14 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>on</power>
<loi_distance name="AcmeHQ" unit="Miles" inside="0">95.4</loi_distance>
</asset>
</currentlocations>
Example XML Request (multiple assets)
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&startrow=0&count=10&sortfield=lasttime&sortdir=asc
Example Success Reply XML
<?xml version="1.0"?>
<currentlocations>
<asset tagid="" fleet="GSM_8306_Ryan" id="182" type="0">
<long>47.4276639</long>
<lat>-122.2940209</lat>
<heading>358.290000</heading>
<time>2007-05-23 14:14 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>on</power>
</asset>
<asset tagid="" fleet="gsm_12589_dave_test" id="199" type="0">
<long>45.5001475</long>
<lat>-108.9651831</lat>
<heading>238.820000</heading>
<time>2007-05-29 06:13 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="508" fleet="revD_508_TestBed" id="210" type="0">
<long>47.4275273</long>
<lat>-122.2950469</lat>
<heading>171.280000</heading>
<time>2007-06-05 16:41 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="509" fleet="revD_509_TestBed" id="211" type="0">
<long>47.4275227</long>
<lat>-122.2949583</lat>
<heading>147.280000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="506" fleet="revD_506_TestBed" id="208" type="0">
<long>47.4274939</long>
<lat>-122.2949861</lat>
<heading>332.830000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="512" fleet="revD_512_TestBed" id="214" type="0">
<long>47.4274988</long>
<lat>-122.2949991</lat>
<heading>329.740000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="503" fleet="revD_503_TestBed" id="205" type="0">
<long>47.427519</long>
<lat>-122.2950128</lat>
<heading>232.790000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="511" fleet="revD_511_TestBed" id="213" type="0">
<long>47.4274531</long>
<lat>-122.2950165</lat>
<heading>110.150000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="514" fleet="revD_514_TestBed" id="216" type="0">
<long>47.4274849</long>
<lat>-122.2950011</lat>
<heading>161.430000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
<asset tagid="507" fleet="revD_507_TestBed" id="209" type="0">
<long>47.4275373</long>
<lat>-122.2950539</lat>
<heading>332.830000</heading>
<time>2007-06-05 17:00 PDT</time>
<speed unit="Mile/Hour">0</speed>
<power>off</power>
</asset>
</currentlocations>
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)*>
Example KML "Current Location" Request with target specified
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=kml&reqtype=dbid&target=19&version=2&logvers=3
Example KML "Current Location" Success reply (KML)
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="https://earth.google.com/kml/2.0">
<Document>
<name>19/Sep/2006 16:18:08</name>
<description>Last Known Location information retrieved on 19/Sep/2006 16:18:08</description>
<!-- Begin Style Definitions -->
<Style id="green_dot">
<IconStyle>
<Icon>
<href>root://icons/palette-4.png</href>
<y>160</y>
<w>32</w>
<h>32</h>
</Icon>
</IconStyle>
</Style>
<Style id="red_dot">
<IconStyle>
<Icon>
<href>root://icons/palette-4.png</href>
<y>32</y>
<w>32</w>
<h>32</h>
<x>224</x>
</Icon>
</IconStyle>
</Style>
<Style id="green_car">
<IconStyle>
<Icon>
<href>root://icons/palette-4.png</href>
<x>192</x>
<w>32</w>
<h>32</h>
</Icon>
</IconStyle>
</Style>
<Style id="cold_start_icon">
<IconStyle>
<Icon>
<href>root://icons/palette-4.png</href>
<x>96</x>
<y>96</y>
<w>32</w>
<h>32</h>
</Icon>
</IconStyle>
</Style>
<Style id="sc_one">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<y>192</y>
</Icon>
</IconStyle>
</Style>
<Style id="sc_two">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<x>32</x>
<y>192</y>
</Icon>
</IconStyle>
</Style>
<Style id="sc_three">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<x>64</x>
<y>192</y>
</Icon>
</IconStyle>
</Style>
<Style id="sc_four">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<x>96</x>
<y>192</y>
</Icon>
</IconStyle>
</Style>
<Style id="sc_five">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<x>128</x>
<y>192</y>
</Icon>
</IconStyle>
</Style>
<Style id="geofence_icon">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<h>32</h>
<w>32</w>
<x>96</x>
<y>128</y>
</Icon>
</IconStyle>
</Style>
<Style id="switched_off_icon">
<IconStyle>
<Icon>
<href>root://icons/palette-3.png</href>
<x>64</x>
<y>96</y>
<w>32</w>
<h>32</h>
</Icon>
</IconStyle>
</Style>
<Style>
<LineStyle>
<color>ffeeee17</color>
<width>4</width>
</LineStyle>
</Style>
<!-- End Style Definitions -->
<Folder>
<name>Fleet: 900_1997_kelly TagId: 1003 Type: 0 Id: 19</name>
<Folder>
<name>Last Location</name>
<description>This point is the last known location logged for this asset</description>
<Placemark>
<description>
<![CDATA[
<div align="center">
<table cellspacing="1" cellpadding="1" border="1">
<tr><td nowrap><font face="verdana" size="5">Time:</font></td>
<td nowrap><font face="verdana" size="5">2006-09-18 09:34:54-07</font></td>
</tr>
<tr> <td nowrap><font face="verdana" size="5">Speed:</font></td>
<td nowrap><font face="verdana" size="5">0.0 Mile/Hour</font></td>
</tr>
<tr> <td nowrap><font face="verdana" size="5">Heading:</font></td>
<td nowrap><font face="verdana" size="5">North </font></td>
</tr>
<tr> <td nowrap><font face="verdana" size="5">Log Reason:</font></td>
<td nowrap><font face="verdana" size="5">Switched Off Power Event </font></td>
</tr>
<tr> <td nowrap><font face="verdana" size="5">Distance Travelled:</font></td>
<td nowrap><font face="verdana" size="5">0.0 Miles</font></td>
</tr>
</table>
</div>
]]>
</description>
<styleUrl>#switched_off_icon</styleUrl>
<TimeInstant>
<timePosition>2006-09-18T09:34:54</timePosition>
</TimeInstant>
<Point>
<coordinates>-122.295077,47.4275229,0.000000</coordinates>
</Point>
</Placemark>
</Folder>
</Folder>
</Document>
</kml>
Binary Data Returned
A binary version 3 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 |
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 |
Example Binary "Current Location" Request
https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=binary&logvers=3&version=
Example Binary "Current Location" Request with target specified
https://customer.zonarsystems.net/interface.php?action=showposition&operation=current&format=binary&reqtype=dbid&target=19&logvers=3&version=2