justice-data-nz git:20260719.1748a98A

Immutable. This exact content never changes and is served at /api/v1/blob/9831be0e3d4645fd.

---
name: justice-data-nz
description: "Query New Zealand Ministry of Justice data tables for finalised charges, convictions, sentencing outcomes, family-violence offences, and youth justice statistics. Use when Codex needs official MoJ justice statistics, workbook URLs, or JSON rows from public no-key justice data tables."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "public-data"
  thecolab.source_owner: "Ministry of Justice"
  thecolab.source_type: "official"
  thecolab.auth: "none"
  thecolab.access_mode: "public-download"
  thecolab.data_class: "public"
  thecolab.writes: "false"
  thecolab.browser: "false"
  thecolab.risk: "low"
  thecolab.cache_ttl: "24h"
  thecolab.schema_version: "1"
  thecolab.skill_type: "public-download"
  thecolab.pack: "nz-public-data"
  thecolab.source_url: "https://www.justice.govt.nz/justice-sector-policy/research-data/justice-statistics/data-tables/"
  thecolab.allowed_domains: "catalogue.data.govt.nz,www.justice.govt.nz"
  thecolab.last_verified: "2026-07-19"
  thecolab.health: "gated"
  thecolab.maintainer: "@adam91holt"
---

# Justice Data NZ

## Goal

Query official Ministry of Justice public data tables through a deterministic CLI with human-readable and JSON output.

## Use this when

- A user asks for New Zealand court charges, conviction, sentencing, family-violence, or youth-justice statistics
- A workflow needs a current Ministry of Justice data-table workbook URL
- Another tool or agent needs machine-readable rows for a given table year
- A user needs to cite the MoJ data-tables source rather than one-off PDF summaries

## Do not use this for

- Police-recorded victimisations, proceedings, or calls-for-service data
- Corrections prison muster, remand, parole, or sentence-management data
- Stats NZ table-builder extraction unless the user specifically asks for Stats NZ mirrors
- Private court data, suppressed case details, or authenticated Ministry systems

## Preferred workflow

1. Run `scripts/cli.py tables --json` to discover the current Ministry of Justice workbook URLs
2. Use `convictions --year YYYY` for people convicted plus finalised and convicted charges by offence
3. Use `sentencing --year YYYY` for sentencing outcomes for people and convicted charges
4. Use `family-violence --year YYYY` for family-violence offence counts, outcomes, convictions, and sentences
5. Use `youth --year YYYY` for children and young people statistics; add `--scope youth-court` for Youth Court-only data
6. Use `--json` when another tool or agent needs machine-readable output
7. Mention the Ministry of Justice as the upstream source and include the workbook URL when reporting figures

## CLI

Run with:

```bash
python3 skills/justice-data-nz/scripts/cli.py <command> [flags]
```

Commands:

- `tables [--query TEXT] [--limit N] [--json]` - list available MoJ data-table workbooks
- `convictions --year YYYY [--offence TEXT] [--json]` - people convicted, finalised charges, and convicted charges by offence
- `sentencing --year YYYY [--json]` - people convicted and convicted charges by most serious sentence
- `family-violence --year YYYY [--offence TEXT] [--json]` - family-violence offence, outcome, conviction, and sentence series
- `youth --year YYYY [--scope any-court|youth-court] [--age-group TEXT|all] [--offence TEXT] [--json]` - youth justice charge, people, offence, and order series

Examples:

```bash
python3 skills/justice-data-nz/scripts/cli.py tables --json
python3 skills/justice-data-nz/scripts/cli.py convictions --year 2025 --offence assault --json
python3 skills/justice-data-nz/scripts/cli.py sentencing --year 2025
python3 skills/justice-data-nz/scripts/cli.py family-violence --year 2025 --json
python3 skills/justice-data-nz/scripts/cli.py youth --year 2025 --scope youth-court --json
```

## Resources

- CLI entrypoint: `scripts/cli.py`
- Smoke test: `scripts/smoke_test.py`
- Source and fallback notes: `references/api-notes.md`

## Notes

- The CLI uses public, no-key Ministry of Justice workbook downloads linked from the data-tables page
- Workbooks are parsed with Python standard-library `zipfile` and XML tools; no external packages are required
- `tables` can fall back to data.govt.nz CKAN metadata if the MoJ page is blocked, but current values require the direct MoJ workbook downloads
- Every network call has a timeout and upstream failures are reported as clear user-facing errors