Elections 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

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 records retain reporting-period and disclosure-threshold context.
• Do not derive voter-level profiles or political persuasion.

Result commands parse the Commission's published CSV tables and finance commands return matching first-party return documents. It never converts a parser failure into an empty success. Follow linked primary records for definitions and reporting-period context.

Resources

• scripts/cli.py — canonical command entrypoint
• scripts/test_contract.py — deterministic repository contract audit
• scripts/smoke_test.py — parser fixture and bounded live probe
• tests/fixtures/overall-results.csv, turnout.csv, winning-candidates.csv and finance.html — export-specific fixtures
• references/source-notes.md — feasibility, provenance and source limits