26.0 Export Current Location

Export the last location of one or more assets. Data is returned as either standard KML log file or as a binary 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

26.1 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	OMI protocol version - version 2 only
logvers	2 is available with `format=xml` or `format=csv` 3 is only available with `format=binary` 3.1 adds odometer value and is only available with `format=xml` 3.2 formats the `<time>` value as epoch and is only available with `format=xml` 3.3 adds GPS odometer offset value to odometer return value. Only available with `format=xml`
Optional Information
target	Identifies one particular asset according to reqtype.
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.
count	The maximum number of results to return. Note: Only valid for xml and kml
sortfield	Field to sort results by. Acceptable values: `fleet` is the fleet number. `lasttime` is the last time stamp at the last location. `speed` is the speed at the last location. `poweron` is the status of the poweron bit. Note: Only valid for xml and kml
sortdir	Direction results are to be sorted by. Acceptable values: `asc` `desc` 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: `on` `Note: Only valid for xml and kml`
loilocation	A LOI* name. If supplied, the distance from the asset to the center of this LOI is returned.
loifilter	An LOI* ID. If supplied, only assets within this LOI are returned.
loicatfilter	An LOI* Category ID. If supplied, only assets within this LOIs in this category are returned.
include_loi	An LOI* 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.

26.2 Data Returned

A standard KML log file, XML, binary version 3 GPS log file or an XML error message.

26.2A XML Returned data

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>

logvers=3.1 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>

<!ELEMENT odometer (#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 LOI distance
inside (loi_distance)	0 or 1 to indicate the asset is outside or inside the LOI respectively
odometer	odometer value measured in meters.

Example XML Request (single asset):

http://gpsdev.zonarsystems.net/interface.php?action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&target=182&reqtype=dbid

Example Success Reply (XML):

Reply

Example XML Request (single asset, with location):

http://gpsdev.zonarsystems.net/interface.php?action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&target=182&reqtype=dbid&loilocation=AcmeHQ

Example Success Reply (XML):

Reply

Example XML Request (multiple assets):

http://gpsdev.zonarsystems.net/interface.php?action=showposition&operation=current&format=xml&version=2&logvers=3&customer=cfg0013&startrow=0&count=10&sortfield=lasttime&sortdir=asc

Example Success Reply (XML):

Reply

26.2B KML Returned data

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:

http://customer.zonarsystems.net/interface.php?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="http://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>  <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>  <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>

26.2C Binary Returned data

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:

http://customer.zonarsystems.net/interface.php?action=showposition&operation=current&format=binary&logvers=3&version=2

Example binary "Current Location" Request with target specified:

http://customer.zonarsystems.net/interface.php?action=showposition&operation=current&format=binary&reqtype=dbid&target=19&logvers=3&version=2

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