NZ Schools

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

# search schools and directory resources
python3 scripts/cli.py search QUERY --json
# find a school by Ministry number
python3 scripts/cli.py school ID --json
# discover schools near valid WGS84 coordinates
python3 scripts/cli.py near --lat VALUE --lon VALUE --json
# discover official enrolment-zone resources
python3 scripts/cli.py zone --address VALUE --json
# filter by region
python3 scripts/cli.py region NAME --json
# discover school changes since an ISO date
python3 scripts/cli.py changes --since YYYY-MM-DD --json

Add --limit N (1–100) to bound any command. Human output is the default. Latitude must be between -90 and 90, longitude between -180 and 180, and --since must be a valid YYYY-MM-DD date. Invalid values fail before the nightly source download.

Coverage and interpretation

• Directory fields are not school rankings or quality claims.
• Enrolment-zone boundaries can change and require official school confirmation.
• No student-level or small-cell information is returned.

The Ministry publishes the Schools Directory as a nightly data.govt.nz DataStore resource. The CLI reads that official resource and its modification timestamp, normalises directory fields, and performs local search, region, Ministry-number and coordinate-distance queries. changes reports opening dates present in the current directory with an explicit partial-coverage warning. zone --address is unsupported until an authoritative geocoder and current zone geometry can be combined without guessing.

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/schools.json — representative official-schema records
• references/source-profile.json — command schema, source allowlist and warnings
• references/source-notes.md — feasibility, provenance and source limits