Skip to content

Reports

A report is a generated artifact — a heatmap image, an aggregated event report, or a CSV. The SDK exposes four distinct flows: heatmap (POST + poll), PWS (paginate + aggregate), zone-activity CSV (chunked download), alarms CSV (with optional banner).

Quick reference

Method What it does
client.reports.list(*, site_uid, start, end, type) List existing reports of a given ReportType in a window.
client.reports.get(uid, *, is_output_file=False) Fetch one report's metadata.
client.reports.heatmap(*, start, end, tag_uids, names=None, poll_interval=2.0, timeout=None) Generate a heatmap; POST + poll until ready.
client.reports.pws(*, trackable_uid, start, end, timezone=None) Aggregate all PWS-event pages into one PwsReport.
client.reports.zone_activity_csv(*, start, end, area_uids, stream_to=None, dedup_headers=True) Chunked zone-activity CSV; in-memory or streamed.
client.reports.alarms_csv(*, start, end, site_uid, alarm_types=None, include_banner=True) Alarms CSV with optional multi-line banner prefix.

Heatmap — polling

from datetime import datetime, timezone

start = datetime(2024, 1, 1, tzinfo=timezone.utc)
end   = datetime(2024, 1, 2, tzinfo=timezone.utc)

heatmap = client.reports.heatmap(
    start=start, end=end, tag_uids=["t-1", "t-2"], timeout=300.0,
)
print(heatmap.image_url)

The SDK POSTs /api/v2/obsolete/report then polls until output.url is populated. Outcomes:

  • Heatmap returned with image_url set on success.
  • ReportFailed if the server reports error in the poll body.
  • ReportTimeout if polling exceeds timeout. The exception carries report_uid so you can resume via client.reports.get(uid).

timeout=None (default) is unbounded — useful for batch jobs.

PWS event aggregation

report = client.reports.pws(
    trackable_uid=["t-1", "t-2"], start=start, end=end, timezone="UTC",
)
print(len(report.events))

Materializes every page into one PwsReport. For unbounded windows prefer the iterator surface — see Events.

CSV downloads

Zone-activity (chunked)

blob = client.reports.zone_activity_csv(
    start=start, end=end, area_uids=["a-1", "a-2"],
)
blob.write_to("zone-activity.csv")

The server returns the CSV in chunks via content-next-page. The SDK follows the chain, strips duplicate header rows (toggle with dedup_headers=False), and returns one coherent CSV blob. Pass stream_to=<file> to write incrementally and return None.

Alarms

blob = client.reports.alarms_csv(
    start=start, end=end, site_uid="s-1", alarm_types=["fall", "battery_low"],
)
blob.write_to("alarms.csv")

include_banner=True (the default) prepends the multi-line `#Site /

From / #To` banner the JS reference client emits.

Models — Heatmap, PwsReport, Report

Heatmap:

Field Type Notes
uid str Server-assigned.
image_url str Absolute URL for the generated image.
name str \| None Display label.
input HeatmapInput \| None Echo of the generation parameters.
output_metadata dict Server-provided extras.

PwsReport:

Field Type Notes
events list[PwsEvent] Materialized events.
total_count int \| None Server-reported total (Style 2 pagination).
timezone str \| None The requested timezone.

Report (returned by list / get) has uid, name, type, status.

Full field list.

  • Events: PWS event streams power both reports.pws (aggregate) and events.iter_pws (iterator). See Events.
  • Tags: tag_uids= filters most reports. See Tags.
  • Sites / Areas: alarms_csv is per-site, zone_activity_csv is per-area. See Sites / Areas.

See also