deprivation-nz - SKILL.md Agent Skill

name: deprivation-nz description: Look up New Zealand small-area socioeconomic deprivation (NZDep2023) by SA1/SA2 code, place name, decile, or SA3 region - the standard index of relative poverty, material hardship, and disadvantage used for health, housing, school decile, child poverty, and funding analysis. No API key or login required.

Deprivation NZ (NZDep2023)

Goal

Query the New Zealand Index of Deprivation 2023 (NZDep2023) through a small deterministic CLI with human-readable and JSON output, without browser automation, login, API keys, or local cache state.

NZDep2023 ranks every small area in New Zealand on relative socioeconomic deprivation. Decile 1 = least deprived, decile 10 = most deprived. It is the standard proxy for area-level poverty, material hardship, and disadvantage used across health, housing, education, and social-policy analysis.

This skill ships support for:

Per-area deprivation decile, raw score, and population for Statistical Area 1 (SA1)
Averaged deprivation decile/score for Statistical Area 2 (SA2), with parent SA3 region
Name search over SA2 area names (returns SA1 or SA2 detail)
Listing areas in a specific deprivation decile
Listing all SA2 areas inside an SA3 region with their deprivation
A national summary of the SA1 decile distribution

Use this when

A user asks how deprived, poor, or disadvantaged a New Zealand suburb, street, or area is
A user needs the NZDep2023 decile or score for an SA1 or SA2 code, or for a named place
A workflow needs area-level deprivation as a proxy for child poverty, material hardship, or need
A user is matching deprivation to health, housing, school decile, or funding allocation
Another tool or agent needs machine-readable NZDep2023 values

Do not use this for

Individual or household income, benefit numbers, or the public housing register (NZDep is area-level only, not person-level)
Geospatial boundary polygons, maps, or GIS overlays (this CLI requests returnGeometry=false)
Older indexes (NZDep2018, NZDep2013) - only the 2023 release is wired
Census microdata or confidentialised unit records
Redistributing the dataset as a standalone product

CLI

Run with:

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

Every command supports --json for machine-readable output; the default is human-readable.

Commands

sa1 --code <SA1_code> [--json] - NZDep2023 decile, score, and population for a 7-digit SA1 area
sa2 --code <SA2_code> [--json] - averaged NZDep2023 decile/score for a 6-digit SA2 area, plus its SA3 region
search --name <text> [--level sa1|sa2] [--limit N] [--json] - find areas whose SA2 name matches text
decile --value <1-10> [--level sa1|sa2] [--limit N] [--json] - list areas in a given deprivation decile
region --sa3 <SA3_name> [--limit N] [--json] - list SA2 areas within an SA3 region with their deprivation
stats [--json] - national count and decile distribution across all SA1 areas

Examples:

python3 skills/deprivation-nz/scripts/cli.py sa1 --code 7000000 --json
python3 skills/deprivation-nz/scripts/cli.py sa2 --code 127100
python3 skills/deprivation-nz/scripts/cli.py search --name "Auckland" --level sa2 --limit 10 --json
python3 skills/deprivation-nz/scripts/cli.py decile --value 10 --level sa2 --limit 20 --json
python3 skills/deprivation-nz/scripts/cli.py region --sa3 "Northcote (Auckland)" --json
python3 skills/deprivation-nz/scripts/cli.py stats --json

Resources

CLI entrypoint: scripts/cli.py
Feature service and field notes: references/api-notes.md

Notes

Source: New Zealand Index of Deprivation 2023 (NZDep2023), University of Auckland / Stats NZ, published as a public ArcGIS Feature Service (no login, no key)
Decile 1 is least deprived; decile 10 is most deprived - always state the direction when reporting
SA1 carries the per-area decile/score/population; SA2 carries area-averaged values plus the parent SA3 region
search and region match on names case-insensitively using an ArcGIS LIKE query; name input is validated to safe characters before being sent
The service caps each query at 2,000 records; use --limit and narrower filters for large regions
Cite NZDep2023 as the upstream source when reporting figures, and note that it measures area-level relative deprivation, not individual circumstances
Default output is human-readable; every command supports --json for chaining into other tools