public-housing-nz - SKILL.md Agent Skill

name: public-housing-nz description: Query New Zealand public and social housing open data from the Ministry of Housing and Urban Development (HUD) on data.govt.nz — public housing stock (Kainga Ora and community housing providers), social housing IRRS and market-rent tenancies, accommodation supplement recipients and weekly spend, and the Local Housing Statistics dashboard (housing affordability, rent burden, bonds, building consents, MSD benefit numbers, and the year-on-year change in the public/social housing register). Use when the task involves NZ public housing, the social housing register or wait-list, Kainga Ora, housing deprivation, accommodation supplement, housing affordability, or HUD housing statistics. No API key, login, or browser session required.

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.