Status Operational Status

List Personnel (Z Pass / Ridership) Events

  • Last edited on

Request Data

This function retrieves personnel events from the system.

This function is only available in version 2.X of the API.

cardtype Type of card scans to return. Acceptable values are:

  • student - Return events for student card scans
  • driver - Return events for driver card scans (requires logvers 3).
  • both - Return events for both driver and student card scans (requires logvers 3).

Default value is student for logvers <= 2. Default is both for logvers >= 3.

Information Required
Name Description
action showevents
operation list
format xml
Optional Information
location Location to filter with. Text. If provided only data associated with assets assigned to this location will be returned.
start Epoch timestamp. If specified only data with a timestamp after this time will be returned. May be combined with end to specify a particular time period.
end Epoch timestamp. If specified only data with a timestamp before this time will be returned. May be combined with start to specify a particular time period.
target Specific asset to report data for, rather than entire fleet. If specified then reqtype must be specified as well. See asset target for details.
reqtype Flag to identify the key being used to query. Acceptable values:
  • tag Key is a Zonar RFID tag number. In version 2 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 id number. This is the most reliable key to use.
  • fleet Key is the asset fleet number. In version 2 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.
perstarget Filter output data by tag id. It is possible to have more than one person's scans returned if the cardtype = both and there is a rider and driver card that share the same tag id.
tstype Determines which time stamp to filter by, valid options are:
  • log
  • load

If tstype is not provided, tstype=log is assumed
logvers Determines what information is output, valid options are:
  • 1 - This is the standard output described below.
  • 2 - This will add a new child element to the event element named address. For XML example see below
  • 3 - This adds support for retrieving driver cards.

If no value is passed, a default value of 1 is assumed.

Data Returned

logvers = 1 DTD

<!ELEMENT persevents (count, event*)>
<!ATTLIST persevents  ver CDATA #REQUIRED>
<!ATTLIST persevents  count CDATA #REQUIRED>
<!ELEMENT event  (asset?, personnel)>
<!ATTLIST event  timestamp CDATA #REQUIRED>
<!ATTLIST event  sn CDATA #REQUIRED>
<!ATTLIST event  type CDATA #REQUIRED>
<!ATTLIST event  latlong CDATA #REQUIRED>
<!ATTLIST event  loiname CDATA #REQUIRED>
<!ELEMENT asset  (fleet, assetid, assettag, exsid, assettype)>
<!ELEMENT asset  fleet CDATA #REQUIRED>
<!ELEMENT asset  assetid CDATA #REQUIRED>
<!ELEMENT asset  assettag CDATA #REQUIRED>
<!ELEMENT asset  exsid CDATA #REQUIRED>
<!ELEMENT asset  assettype CDATA #REQUIRED>
<!ELEMENT personnel  (tagid, ptype)>
<!ELEMENT personnel  tagid CDATA #REQUIRED>
<!ELEMENT personnel  ptype CDATA #REQUIRED>

 

logvers = 2 student DTD

<!ELEMENT persevents (count, event*)>
<!ATTLIST persevents  ver CDATA #REQUIRED>
<!ATTLIST persevents  count CDATA #REQUIRED>
<!ELEMENT event  (address, asset?, personnel)>
<!ATTLIST event  timestamp CDATA #REQUIRED>
<!ATTLIST event  sn CDATA #REQUIRED>
<!ATTLIST event  type CDATA #REQUIRED>
<!ATTLIST event  latlong CDATA #REQUIRED>
<!ATTLIST event  loiname CDATA #REQUIRED>
<!ELEMENT address (street, number, zip, city, state, country)>
<!ELEMENT street (#PCDATA)>
<!ELEMENT number (#PCDATA)>
<!ELEMENT zip (#PCDATA)>
<!ELEMENT city (#PCDATA)>
<!ELEMENT state (#PCDATA)>
<!ELEMENT country (#PCDATA)>
<!ELEMENT asset  (fleet, assetid, assettag, exsid, assettype)>
<!ELEMENT fleet CDATA #REQUIRED>
<!ELEMENT assetid CDATA #REQUIRED>
<!ELEMENT assettag CDATA #REQUIRED>
<!ELEMENT exsid CDATA #REQUIRED>
<!ELEMENT assettype CDATA #REQUIRED>
<!ELEMENT personnel  (tagid, ptype)>
<!ELEMENT tagid CDATA #REQUIRED>
<!ELEMENT ptype CDATA #REQUIRED>  

logvers = 3 driver DTD

<!ELEMENT persevents (count, event*)>
<!ATTLIST persevents  ver CDATA #REQUIRED>
<!ATTLIST persevents  count CDATA #REQUIRED>
<!ELEMENT event  (address, asset?, personnel)>
<!ATTLIST event  timestamp CDATA #REQUIRED>
<!ATTLIST event  sn CDATA #REQUIRED>
<!ATTLIST event  type CDATA #REQUIRED>
<!ATTLIST event  latlong CDATA #REQUIRED>
<!ATTLIST event  loiname CDATA #REQUIRED>
<!ELEMENT address (street, number, zip, city, state, country)>
<!ELEMENT street (#PCDATA)>
<!ELEMENT number (#PCDATA)>
<!ELEMENT zip (#PCDATA)>
<!ELEMENT city (#PCDATA)>
<!ELEMENT state (#PCDATA)>
<!ELEMENT country (#PCDATA)>
<!ELEMENT asset  (fleet, assetid, assettag, exsid, assettype)>
<!ELEMENT fleet CDATA #REQUIRED>
<!ELEMENT assetid CDATA #REQUIRED>
<!ELEMENT assettag CDATA #REQUIRED>
<!ELEMENT exsid CDATA #REQUIRED>
<!ELEMENT assettype CDATA #REQUIRED>
<!ELEMENT personnel  (tagid, fname, lname, exsid)>
<!ATTLIST personnel  cardtype (student|driver) #REQUIRED>
<!ELEMENT tagid CDATA #REQUIRED>
<!ELEMENT fname CDATA #REQUIRED>
<!ELEMENT lname CDATA #REQUIRED>
<!ELEMENT exsid CDATA #REQUIRED>  

Personnel Event Reply

Reply Data
Name Description
version The version number of the API call and return data.
count The number of results returned.
timestamp The time the event occurred. Unix epoch timestamp (UTC).
sn The serial number of the GPS unit that collected the event. A positive integer.
type The type of event that occurred. A short text label identifying the event type. Text, 24 characters maximum length.
latlong The latitude and longitude position of where the event occurred (format: lat,long).
loiname The name of the Location of Interest* that the vehicle was in when the event was logged. This will be either the smallest of the LOIs that the event position is contained within, or in the case of multiple LOIs the most recently added one. Text, 100 characters maximum length.
Asset The asset that was associated with the GPS unit collecting the event data. If the GPS unit question was not assigned to an asset this element will not be present.
fleet The asset fleet number. Usually displayed in the web interface as Asset No. Alphanumeric, 20 characters maximum. This may be empty if the asset does not have a fleet number.
assettag The Zonar RFID tag number of the asset the data is associated with. Numeric either a positive integer or zero. This may be zero if the asset does not have a tag number.
exsid External system identifier of the asset the data is associated with. This may be empty if the asset does not have an exsid. Arbitrary text up to 40 characters in length.
assetype The type of the asset. See asset types for more details.
assetid Database id of the asset the data is associated with. This will be a positive integer.
tagid The RFID tag number used by the individual.
ptype Student only, the type of personnel that the individual is. Text 24 characters maximum length.
fname Driver only, the first name of the driver who created the event.
lname Driver only, the last name of the driver who created the event.
exsid Driver only, the exsid of the driver who created the event.

Example Request

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&format=xml&action=showevents&operation=list&version=2

Example Success Reply logvers=1

<?xml version="1.0"?>
<persevents ver="2.0" count="2">
<event timestamp="1186088047" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Country Road 5">
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel>
 <tagid>31337</tagid>
 <ptype></ptype>
 </personnel>
</event>
<event timestamp="1186088042" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Public School 8">
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel>
 <tagid>31337</tagid>
 <ptype></ptype>
 </personnel>
</event>
</persevents>

Example Success Reply logvers=2

<?xml version="1.0"?>
<persevents ver="2.0" count="2">
<event timestamp="1186088047" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Country Road 5">
 <address>
 <city>Salt Lake City</city>
 <country>United States</country>
 <number>1750 West</number>
 <street>3300 South</street>
 <state>UT</state>
 <zip>84126</zip>
 </address>
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel>
 <tagid>31337</tagid>
 <ptype></ptype>
 </personnel>
</event>
<event timestamp="1186088042" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Public School 8">
 <address>
 <city>Salt Lake City</city>
 <country>United States</country>
 <number>1750 West</number>
 <street>3300 South</street>
 <state>UT</state>
 <zip>84126</zip>
 </address>
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel>
 <tagid>31337</tagid>
 <ptype></ptype>
 </personnel>
</event>
</persevents>

Example Success Reply logvers=3

<?xml version="1.0"?>
<persevents ver="2.0" count="2">
<event timestamp="1186088047" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Country Road 5">
 <address>
 <city>Salt Lake City</city>
 <country>United States</country>
 <number>1750 West</number>
 <street>3300 South</street>
 <state>UT</state>
 <zip>84126</zip>
 </address>
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel cardtype="driver">
 <tagid>12345</tagid>
 <fname>Don</fname>
 <lname>Driver</lname>
 <exsid></exsid>
 </personnel>
</event>
<event timestamp="1186088042" sn="8001" type="VehicleOnOff" latlong="13580977,5910809" loiname="Public School 8">
 <address>
 <city>Salt Lake City</city>
 <country>United States</country>
 <number>1750 West</number>
 <street>3300 South</street>
 <state>UT</state>
 <zip>84126</zip>
 </address>
 <asset>
 <fleet>0080</fleet>
 <assetid>68</assetid>
 <assettag>10080</assettag>
 <exsid></exsid>
 <assettype>0</assettype>
 </asset>
 <personnel cardtype="driver">
 <tagid>9876543</tagid>
 <fname>Smooth</fname>
 <lname>Operator</lname>
 <exsid></exsid>
 </personnel>
</event>
</persevents>

 

Miscellaneous