API reference
This reference describes the documented live integration contract. The historical sample uses packaged data and makes no live API calls. Live availability and service terms are confirmed during onboarding.
# On-air feed v0.2
This document describes the live API contract. Downloaded sample files are fixed
and do not execute query flags. The sample explorer reads included historical files.
The API page also provides a versioned documentation projection in JSON and XML,
with one on_air_status and technical flags grouped in qa. That projection does not
change the documented live schema or existing exports. Keep live credentials on
your integration server. Verify availability, polling,
ETags and retention against the actual broadcast API deployment.
The broadcast API keeps default graphics responses separate from optional evidence.
All routes use existing broadcast key authentication. Concept IDs and canonical
labels come from the database; six display slots do not limit the taxonomy.
```text
GET /api/v1/broadcast/concepts
GET /api/v1/broadcast/design-tokens
GET /api/v1/broadcast/legislators/{id}/on-air?period_start=2026-05-01&period_end=2026-06-01
```
Dates are UTC with an exclusive end. Windows must be 1–366 days. Unknown members
or Concepts return 404. Invalid windows return 400; parameter validation returns
422. The caller's numeric graph Person ID is the existing MVP lookup contract.
## Graphics projections
`view=lower-third` returns `lower_third`, a compact 20-field name-and-one-stat row.
`view=lbar` returns the flat six-topic member row without the analysis catalogue.
The default `view=analysis` also returns one analysis metric per database Concept.
Period, metric, historical/sample status and editorial review status are retained
in every row, including exported CSV/XML. `activity_eligible` is a minimum-volume
check, not a declaration that a graphic is verified. `review_required` is true and
`air_ready` is false pending editorial acceptance. Fields must be bound explicitly.
Topic colours/short labels are shared presentation metadata keyed to the database
Concept. Canonical labels are retained. Unknown Concepts remain present with neutral
colours and an unconfigured status. `/design-tokens` supplies the same proposed
palette to PWA consumers. Party abbreviations and colours are proposed metadata,
not a claim of official branding approval. Structured name parts and portrait URLs
are read from database properties. Basic roles are used when office titles are
missing; no cabinet position or image filename is fabricated. Proposed riding
aliases have a 24-character limit; missing aliases and glyph checks are explicit.
`member_key` is based on an official federal source ID where available, otherwise
on the member's source URL hash, falling back to the graph ID. `member_key_basis`
records the basis. `operator_key` is a readable name key with a hash suffix.
`review_roster_key` preserves the prior pack's roster identity. Source-URL-derived
keys are not approved permanent public IDs. Select by a key, never an array index.
## Exact overview-to-evidence matching
The first request captures date-bounded contribution text and classifications,
computes counts from those very records, and stores an immutable, content-addressed
analysis. The response remains lean: evidence is omitted unless requested.
Captures are capped at 5,000 contributions and 32 MiB; larger requests return 413
and must use a shorter period. This trades an initial bounded read for reproducible
verification. Subsequent unpinned polls reuse the capture for 60 seconds.
Each analysis entry's `evidence_url` pins `analysis_id`, member, period and Concept.
Follow that URL or supply the same ID explicitly:
```text
.../on-air?period_start=2026-05-01&period_end=2026-06-01&include_evidence=true&analysis_id=onair-HASH&topic_id=CONCEPT_ID
```
`evidence_limit` defaults to 20 (maximum 50); follow `next_offset` with
`evidence_offset`. The same retained analysis is used across pages even if the graph
changes. Source text, membership, classifications and display inputs affect the
analysis hash; timestamps alone do not. Unchanged content retains its revision.
An unavailable/expired capture returns 410, never replacement live evidence.
A valid ID for another member or period returns 409. Unsupported presentation
versions also fail closed. Snapshot retention is seven days from last validation.
Responses include a private ETag. Poll the same URL with `If-None-Match` to receive
304 when that representation is unchanged. The analysis revision is also present
in the row; different projections/evidence pages have distinct ETags.
The SQLite capture store defaults to a temporary local path. Configure
`BROADCAST_SNAPSHOT_PATH` for durable storage. All replicas need access to the same
store or pinned requests must stay on the owning instance; otherwise they return
410. A temporary local database is not durable shared Lambda storage. Read
transactions and a 10-second timeout apply; there are no graph writes.
## Metrics and sources
A contribution counts once per kind and Concept even with multiple matching fine
Topics. Contributions can appear in several Concepts. Share is the percentage of
all captured member contributions tagged with the Concept; unclassified records
remain in the denominator. Shares may sum above 100%. They are neither speaking
time nor effectiveness. Ties share competition ranks. The provisional minimum
largest-topic count is 3; below it graphic slots are hidden with neutral fallback
wording. Source counts and evidence remain inspectable.
Live cohort bars use the same current government and stored role and the exact
requested dates; the roster is capped at 600. Multiple governments, missing role
matches or larger rosters make comparison unavailable. The review pack instead
uses its selected 93 MLA/43 BC MP rosters and labels that scope. Neither scaled
bar is a percentage of attention. Existing snapshot graphics expose their own
snapshot-wide maximum and use the same topic colours, tie flags and activity rule.
Evidence includes full stored contribution text or bill summary, source URLs,
original stored references, and Topic-to-Concept mappings. A stored contribution
may be shorter than a full sitting transcript. BC archive resolution is shared by
API and exporter, including the previously established April 29 published-transcript
replacement. Links are marked as not rechecked rather than silently certified.
Missing text and source references remain explicit. Historical activity does not
establish historical party or office: current stored identity is labelled separately.
## Review export and external acceptance
`python -m goverlytics_api_v2.script.upgrade_onair_review` creates a new v2 directory
from preserved database evidence and the bounded current-identity read. It includes
JSON/CSV/XML projections, paired summaries/evidence, proposed design tokens, SVG
reference icons, a browser preview and an offline validator. Original exports remain
unchanged. Static downloads do not execute query flags. Their captured versions
are independent of captures retained by a deployed API.
Cabinet/critic titles require a verified dated source ingested into the database.
Headshot redistribution, approved branding, font coverage and actual PWA card URLs
need verification. No live QR destination is invented. The pack includes a Ross
binding plan and acceptance checklist; it does not claim a tested XPression scene.