public-housing-nz

Public Housing NZ

Overview

Read-only stdlib CLI over the Ministry of Housing and Urban Development (HUD) open-data releases published on data.govt.nz (CKAN at catalogue.data.govt.nz). Every command supports --json for machine-readable output and a human-readable default. No login, API key, browser automation, or cache state.

Covered data:

• Public housing stock by territorial authority and provider (Kainga Ora / CHP)
• Social housing tenancies (Income-Related Rent Subsidy + market rent) by TLA
• Accommodation Supplement recipients and total weekly spend by area
• Local Housing Statistics dashboard: affordability, rent burden, bonds, building consents, sales, census crowding, MSD figures, population, and the 1-year change in the Housing Register
• CKAN catalogue discovery and server-side DataStore filtering

When to Use

• A user asks about NZ public/social housing stock, Kainga Ora, or CHP homes
• A user wants social housing tenancy counts (IRRS + market rent) by district
• A user asks about the Accommodation Supplement (recipients, weekly cost)
• A user asks about housing affordability, rent burden, or the change in the housing register / social housing wait-list trend
• Another tool needs no-login, machine-readable HUD housing data as JSON

Do not use this for

• The exact current Public/Social Housing Register wait-list headcount — HUD publishes that as XLSX/HTML, not clean CSV (see Notes); this skill exposes the Local Housing Statistics dashboard's change in register series instead
• Private, unpublished, or authenticated MSD/HUD data
• Redistributing the public extracts as a standalone dataset

Commands

Run with:

python3 skills/public-housing-nz/scripts/cli.py <command> [flags]

• datasets [--query Q] [--limit N] [--json] - list HUD housing datasets/resources via CKAN package_search (format + last-modified)
• public-homes [--area AREA] [--provider KO|CHP] [--date YYYY-MM-DD] [--json] - public housing stock; defaults to the latest as-at date
• tenancies [--area TLA] [--date YYYY-MM-DD] [--json] - social housing (IRRS + market rent) tenancies by TLA; defaults to latest date
• accommodation-supplement [--area AREA] [--area-type TLA] [--date YYYY-MM-DD] [--json] - AS recipients and weekly spend; defaults to latest date
• local-stats [--area NAME] [--theme THEME] [--series SERIES] [--year YYYY] [--limit N] [--json] - Local Housing Statistics dashboard rows
• series [--json] - list the distinct series and themes available in local-stats
• query --resource sochouse|publichomes|as|local [--filter k=v ...] [--q TEXT] [--limit N] [--json] - passthrough to CKAN datastore_search for server-side filtering

Examples

python3 skills/public-housing-nz/scripts/cli.py datasets --json
python3 skills/public-housing-nz/scripts/cli.py public-homes --provider KO --json
python3 skills/public-housing-nz/scripts/cli.py tenancies --area "Invercargill City" --json
python3 skills/public-housing-nz/scripts/cli.py accommodation-supplement --area Ashburton --json
python3 skills/public-housing-nz/scripts/cli.py local-stats --series "Change in Housing Register" --json
python3 skills/public-housing-nz/scripts/cli.py local-stats --area "New Zealand" --theme Affordability --year 2024 --json
python3 skills/public-housing-nz/scripts/cli.py series --json
python3 skills/public-housing-nz/scripts/cli.py query --resource sochouse --filter TLA_Name="WHANGAREI DISTRICT" --json

Resources

• CLI entrypoint: scripts/cli.py
• Endpoint and dataset notes: references/api-notes.md

Notes

• All data is published by the Ministry of Housing and Urban Development (HUD) on data.govt.nz; mention HUD as the source and include the release URL.
• No API key, username, password, cookie, or browser session is required.
• tenancies, public-homes, and accommodation-supplement default to the latest as-at date in the file when --date is omitted.
• Suppressed values in the public-homes file appear as s; the CLI reports these rows as null and counts them under suppressed_rows.
• The publichomes resource is geolocated by numeric TLA code (its Area_Name is mostly codes, plus a "Not geolocated" rollup), so use --provider and --date; use tenancies for clean TLA-name social housing counts.
• The actual current Public/Social Housing Register wait-list headcount is published by HUD as XLSX + HTML, not clean CSV, so it is intentionally not wired; use local-stats --series "Change in Housing Register" for the register trend, or datasets to discover the latest register release.
• query is a thin passthrough to CKAN datastore_search; CKAN returns dates as ISO datetimes (e.g. 2022-12-31T00:00:00).
• Default output is human-readable; every command supports --json.
• Avoid high-volume polling; use date and area filters or the query passthrough.