elections-nz
Query official New Zealand election results, electorate voting, turnout, aggregate party political finance and reporting rules from the Electoral Commission.
SKILL.mdskills/elections-nz/SKILL.md
GitHubElections NZ
Use the read-only Python CLI to retrieve and filter records exposed by the official first-party source.
Every command supports --json, bounded requests, stable exit codes, source URLs and retrieval timestamps.
Commands
# discover election results
python3 scripts/cli.py results --year VALUE --json
# discover electorate results
python3 scripts/cli.py electorate NAME --year VALUE --json
# discover party-vote results
python3 scripts/cli.py party-vote --year VALUE --json
# discover turnout series
python3 scripts/cli.py turnout --year VALUE --json
# discover candidate results
python3 scripts/cli.py candidate NAME --year VALUE --json
# discover party donation returns
python3 scripts/cli.py donations --party VALUE --json
# discover candidate expense returns
python3 scripts/cli.py expenses --candidate VALUE --json
# query Commission-published annual donation/loan aggregates (optional party filter)
python3 scripts/cli.py finance-aggregates [PARTY] --kind annual --year 2025 --json
# query Commission-published election-expense aggregates
python3 scripts/cli.py finance-aggregates [PARTY] --kind expenses --year 2023 --json
# retrieve exact source-wording rules (optional topic filter)
python3 scripts/cli.py finance-rules [TOPIC] --kind annual --year 2025 --json
Add --limit N (1–100) to bound any command. Human output is the default.
Coverage and interpretation
- Only Electoral Commission outcomes are authoritative.
- Preserve preliminary versus official status and publication date.
- Finance aggregates retain reporting period, metric and missing-value context. Donation, loan, expense, expense-limit and broadcasting metrics remain distinct.
- Reporting rules preserve source wording and mentioned amounts. Unknown effective dates stay unknown; this output is not legal advice.
- Finance aggregation uses only the Commission's published party-summary tables. It never extracts donor/contributor names, addresses or donor-level records, and never recomputes totals from detailed schedules.
- Do not derive voter-level profiles or political persuasion.
Result commands parse the Commission's published CSV tables. Existing donations and expenses commands continue to return matching first-party return documents. finance-aggregates returns structured party-summary facts; finance-rules returns scoped official wording. A valid unmatched filter is an empty success, while source-layout or amount drift fails explicitly.
Resources
scripts/cli.py— canonical command entrypointscripts/test_contract.py— deterministic repository contract auditscripts/test_finance.py— aggregate-only, adversarial and CLI-state testsscripts/smoke_test.py— parser fixture and bounded live probetests/fixtures/overall-results.csv,turnout.csv,winning-candidates.csv,finance.html,finance-annual.htmlandfinance-expenses.html— scrubbed export-specific fixturesreferences/source-notes.md— feasibility, provenance and source limits