SAFR can generate thousands of events in a very short time. An event database with a 30 day event retention (a common setting) can easily grow to contain tens of millions of events. To enable timely access to events, services must often query events in blocks and use pagination to access events. This article demonstrates how to perform event pagination using the SAFR Events Service REST API.

At the end of the article you'll find a sample Python script that demonstrates SAFR Event pagination.

Pagination works by using the following API parameters.

• queryLimit - Number of events to return in a query.  This is often referred to as the page size.
• sortOrder (ascending or descending) - Order that events are read.  If the parameter is set to descending, the first page of events contains the most recent events, and each subsequent page contains older events. 
• minStartDate or maxStartDate (depending on sortOrder) - Specifies the first event in the current page.  
  • Use the value returned in events.paging.lastStartTime from the previous page. (See About max/minStartDate below)
  • Use minStartDate is sortOrder=ascending and maxStartDate if sortOrder is descending.   
  • Not needed on first query (defaults to very first/last event in the result set).

Parameters that impact the time range of events to return:

• sinceTime - The very first event to start pagination from.
• untilTime - The very last event to start pagination from.  Only events that contain an untilTime will apply (see below).

About sinceTime and untilTime

The sinceTime and untilTime parameters allow you to query for specific time ranges of events.

Events that have not ended yet (i.e. the subject is still in view of the camera) will not have an untilTime value and thus won't be included in queries using untilTime. These events may still be included if a startTime condition is met, however.

About maxStartDate and minStartDate

A value for maxStartDate or minStartDate must be provided on the second and all subsequent queries. This tells SAFR where to start for the second page of results. You get the value to pass from the response in the previous page of results.   Each page of results includes a paging object which includes a lastStartTime property.

The syntax for the events response showing just part of one event and the full paging object is as follows:

{
    "events": [
        {
            "eventId": "89AB4DB5-6C6E-47E2-B41B-D4F54A4434A3",
            ...
        },
        ...
    ],
    "paging": {
        "lastStartTime": 1552806512836,
        "firstStartTime": 1552795193769,
        "queryLimit": 100
    }
}

Examples

Paginate ascending through all events using the default queryLimit of 15,000:

Paginate descending through all events using a queryLimit of 1,000:

SAFR Event Paging Python Script Example

A Python script is attached to this article which demonstrates SAFR's pagination capabilities.

Download the file to your hard drive and run the following to view help and usage instructions for the script. as shown.

python pageEvents.py -h