getEvents

Returns a list of historic events.

Note: This function requires an API license.

This command returns a list of specific events for specific cameras. The parameter startid is required to return a list of events. If omitted, or startid is zero or negative, an empty list will be returned with the lastEventId value. The lastEventId value can be used to query for new events.

All other arguments are optional and can be used to filter the kind of event. Filters are and-ed together, meaning the event must match all filters. The argument types is a comma separated list of types (strings) the event must match All events that match one of the types supplied are returned (after ending together with the other filters). If this parameter is omitted, all event types are returned.

The results are always sorted in ascending time. Because of the internal working of the system, it could happen that the order of eventid’s differs from the order of eventtime’s. For example, the result list, ordered by eventtime, could have an eventid sequence of 1, 2, 3, 5, 4, 6.

The result will also give the last event id back. To get only the last event id, issue this command with a zero or negative start id.

Every event in the eventlist has several result fields. Refer to the Event result fields table for a list of all result fields. The value of all event result fields depends on the software version and setup.

The list can be limited by supplying starttime, endtime and/or limit. Refer to chapter
Result list. for an explanation of these parameters.

The parameters deviceid and serverid can be used to get events from a specific device (from a specific server).

Request

command=getEvents&startid=[id]&starttime=[timestamp]&endtime=[timestamp]&types=[string]&limit=[number]&deviceid=[uid]&serverid=[uid]
parameter type remarks
startid [id] events with an id > startid are returned.
starttime [timestamp] events with a (local) timestamp >= startdate are returned.
endtime [timestamp] events with a (local) timestamp <= enddate are returned.
types [string] comma separated list of types the event must match, i.e. Alarm,SceneR.
limit [number] determines the limit of the resulting event count.
deviceid [UID] filters events from a specific device.
serverid [UID] filters events from a specific server.

CarRLicensePlateFound only

parameter type remarks
licenseplate [string] events with the specified license plate are returned (Case sensitive)
licenseplatedistance [number] the number of characters that should match with the entered licenseplate. ( 0 = all chars should match; 1 = one char can differ, 2 = two chars can differ etc.)

Response

<result errorcode="0">
  <events count="[number]" lasteventid="[UID]">
    <event>
      <eventid></eventid>
      <eventtype></eventtype>
      <eventdescription></eventdescription>
      <eventvalue></eventvalue>
      <eventtime></eventtime>
      <serverid></serverid>
      <serverdescription></serverdescription>
      <deviceid></deviceid>
      <devicedescription></devicedescription>
    </event>
    ...
  </events>
 </result>
node value remarks
/result
@errorcode [number] See error codes below
/result/events
@count [number] The number of events.
lastEventId [UID] id of the last event.
/result/events/event
eventid   id of event.
eventype   type of event. (Available in API version < 2.7.1)
eventdescription description of event.
eventvalue value of event.
eventtime   Time stamp of event in UTC time.
serverid   Id of server where the event occurred.
serverdescription   Description of the server
deviceid   Id of device which triggered the event.
devicedescription Description of the device
error code description remarks
0 Ok Ok, no error
-2 No device No device found for the supplied camareaid/deviceid
-4 Invalid timestamp Invalid datetime format. See Timestamp.

See Also

Changelog

2.7.2 Added licenseplate and licenseplatedistance parameters for CarRLicensePlateFound events.
2.1.1 Times are in UTC times (unless CompatibilityMode1 is activated)
1.12.3 Documented if timestamps are local or UTC timestamps.1.11.3    Strict checking on starttime and endtime parameter format. Returns -4 on error
1.11.1 Corrected the attribute name for time in the documentation. It must be types
1.11.1 Added cameraid and serverid filter.
1.10.2 Allows negative limit and endtime before starttime to reverse the ordering of the result list. Corrected the attributes names in the documentation for startdate and enddate, they are starttime and endtime
1.10.1 Changed default limit from 100 to 25.
1.4.1 Added parameters type and limit.
1.3.9 Fixed arguments. They are now startid, startdate and starttime. Changed limit from 1000 to 100.
1.3.7 Moved attributed eventCount and lastEventId to tag events Renamed eventCount to count.
1.3.3 Limit to 1000 result records
1.3.2 Added count as attribute to result tag.
1.3.1 Added

Example

Retrieve the last evenid..

To get the latest event id ommit the startid or give it a zero or negative value.
Command url:

command=getEvents&startid=0

Result:

<result errorcode="0">
  <events count="0" lasteventid="39993299">
  </events>
 </result>