Skip to content

Events

The events surface exposes two server-side event streams: PWS events (proximity / position) and zone events (entry / exit). PWS is paginated; zone events return as a flat list per window.

Quick reference

Method What it does
client.events.iter_pws(*, trackable_uid, start, end, page_size=1000) Lazy iterator over PWS events; fetches pages on demand.
client.events.pages(*, ...) Same data, yields Page[PwsEvent] so callers can inspect totals.
client.events.list_zone_events(*, area_uid, start, end, **filters) Zone entry / exit events in a window.

Iterating PWS events

for event in client.events.iter_pws(trackable_uid="t-1", start=start, end=end):
    process(event)

trackable_uid accepts a single uid or a list (Rails array param — track_uid[]=).

For progress reporting:

for page in client.events.pages(trackable_uid="t-1", start=start, end=end):
    print(f"page {page.page_number}: {len(page.items)} events")
    if page.total_count is not None:
        print(f"total reported: {page.total_count}")

For windows that fit in memory, the materializing aggregate client.reports.pws(...) is one method instead of a loop — see Reports.

Zone events

client.events.list_zone_events(area_uid=area.uid, start=start, end=end) returns a list of ZoneEvent (each with zone_uid, trackable_uid, event_type like "enter" / "exit", and a tz-aware ts).

Models — PwsEvent, ZoneEvent

PwsEvent:

Field Type Notes
uid str \| None Server-assigned.
trackable_uid str \| None The tag this event is about.
zone_uid str \| None Zone context (if any).
ts int \| float \| None Server timestamp (Unix ms).
type str \| None Event sub-type.

ZoneEvent has uid, zone_uid, trackable_uid, event_type, ts.

Full field list.

  • Tags: filter by trackable_uid. See Tags.
  • Zones: list_zone_events is per-area; zone entry/exit attribution uses the Zone uid.
  • Reports: aggregate / CSV alternatives. See Reports.

See also