NZ Legislation Tool API - v1.2.0

NZ Legislation Tool

Search, retrieve, and cite New Zealand legislation in seconds.

A fast, friendly command-line tool for researchers, legal professionals, and anyone working with NZ legislation. Get your research done faster—with less copying and pasting.

Package links: npm package · GitHub repository

📦 Package Registries

Primary npm package: nz-legislation-tool
GitHub Packages mirror: @edithatogo/nz-legislation-tool

The GitHub repository "Packages" area is populated by GitHub Packages publishes, not by the public npmjs.com listing. This repository includes a workflow to publish a scoped GitHub Packages mirror so the repo can show a package entry there as well.

🚪 Choose Your Interface

CLI

Use the CLI if you want direct terminal access for search, retrieval, export, and citation.

npm install -g nz-legislation-tool
nzlegislation search --query "health act"

MCP Server

Use the MCP server if you want to connect the tool to an AI assistant or tool-calling environment.

npm install -g nz-legislation-tool
nzlegislation-mcp

Example MCP command configuration:

{
  "command": "nzlegislation-mcp",
  "env": {
    "NZ_LEGISLATION_API_KEY": "your-api-key"
  }
}

✨ What You Can Do

🔍 Search - Find legislation by keyword, type, status, or date range
📄 Retrieve - Get full details and version history by ID
📤 Export - Download to CSV or JSON for analysis
📚 Cite - Generate citations in NZMJ, BibTeX, RIS, or APA style
🤖 AI Integration - Connect to AI assistants for automated research
🎨 Beautiful Output - Clean tables, formatted JSON, ready-to-use CSV
🔒 Secure - Your API key stays safe on your machine
📊 Research-Ready - Reproducible exports with full metadata
🧪 Battle-Tested - 43+ automated tests catch issues before you do

🚀 Quick Start (5 Minutes)

Step 1: Get Your API Key (2 minutes)

Visit https://api.legislation.govt.nz/docs/
Sign up for a free API key
Copy the key from your email

Step 2: Install the Tool (1 minute)

Option A: Try without installing (recommended for first time)

npx nz-legislation-tool search --query "health"

Option B: Install globally (recommended for regular use)

npm install -g nz-legislation-tool

Step 3: Set Your API Key (1 minute)

nzlegislation config --key YOUR_API_KEY_HERE

Step 4: Your First Search (30 seconds)

nzlegislation search --query "health act"

You should see:

┌────────────────────┬──────────────────────────────────────────┬────────┬──────────┬────────────┐
│ ID                 │ Title                                    │ Type   │ Status   │ Date       │
├────────────────────┼──────────────────────────────────────────┼────────┼──────────┼────────────┤
│ act/2020/67        │ Health Act 2020                          │ act    │ in-force │ 2020-11-15 │
│ act/1956/65        │ Health Act 1956                          │ act    │ repealed │ 1956-10-01 │
└────────────────────┴──────────────────────────────────────────┴────────┴──────────┴────────────┘

Total: 42 results (showing 25)

🎉 That's it! You're ready to go.

📋 What You Need

Node.js 18.0 or later (Download here)
NZ Legislation API Key (Free - get yours)

📖 Commands (With Examples)

`search` - Find Legislation

Search the entire NZ legislation database.

# Basic search
nzlegislation search --query "health"

# Filter by type (act, bill, regulation, instrument)
nzlegislation search --query "health" --type act

# Filter by status (in-force, repealed, etc.)
nzlegislation search --query "mental health" --status in-force

# Search by date range
nzlegislation search --query "health" --from 2020-01-01 --to 2024-12-31

# Export results to CSV
nzlegislation search --query "health" --format csv --output results.csv

All options:

Option	Short	Description	Default
`--query`	`-q`	Search query (required)	-
`--type`	`-t`	Filter: act, bill, regulation, instrument	-
`--status`	`-s`	Filter: in-force, repealed, etc.	-
`--from`	-	From date (YYYY-MM-DD)	-
`--to`	-	To date (YYYY-MM-DD)	-
`--limit`	`-l`	Max results (1-100)	`25`
`--offset`	`-o`	For pagination	`0`
`--format`	`-f`	Output: table, json, csv	`table`

👉 Pro tip: Use quotes for multi-word searches: "Mental Health Act"

`get` - View Specific Legislation

Get full details for a specific Act or regulation.

# Get details by ID
nzlegislation get "act/2020/67"

# Include version history
nzlegislation get "act/2020/67" --versions

# Output as JSON
nzlegislation get "act/2020/67" --format json

Where do I find the ID?

Run a search first, then copy the ID from the results:

nzlegislation search --query "health act"
# Copy "act/2020/67" from the results

`export` - Download Results to File

Perfect for analysis in Excel, R, or Python.

# Export to CSV (most common)
nzlegislation export --query "health" --output health.csv

# Export to JSON (for developers)
nzlegislation export --query "health" --format json --output health.json

# Filtered export (e.g., only active Acts)
nzlegislation export --query "mental health" --type act --status in-force --output mental_health_acts.csv

# Include metadata for reproducibility
nzlegislation export --query "health" --output health.csv --include-metadata

All options:

Option	Short	Description	Default
`--query`	`-q`	Search query (required)	-
`--output`	`-o`	Output file path (required)	-
`--format`	`-f`	Output: csv, json	`csv`
`--type`	`-t`	Filter by type	-
`--status`	`-s`	Filter by status	-
`--from`	-	From date	-
`--to`	-	To date	-
`--limit`	`-l`	Max results	`100`
`--include-metadata`	-	Add export metadata	`false`

`cite` - Generate Citations

Create citations for papers, theses, or reports.

# NZMJ style (default - for New Zealand Medical Journal)
nzlegislation cite "act/2020/67"

# BibTeX (for LaTeX papers)
nzlegislation cite "act/2020/67" --style bibtex

# RIS (for EndNote, Mendeley, Zotero)
nzlegislation cite "act/2020/67" --style ris

# APA style
nzlegislation cite "act/2020/67" --style apa

Build a bibliography:

# Append multiple citations to a .bib file
nzlegislation cite "act/1981/118" --style bibtex >> references.bib
nzlegislation cite "act/2020/67" --style bibtex >> references.bib

`config` - Manage Settings

View and update your configuration.

# Show current settings
nzlegislation config --show

# Update API key
nzlegislation config --key YOUR_NEW_KEY

# Clear all settings (start fresh)
nzlegislation config --clear

🎯 Real-World Examples

Example 1: Researcher Rachel's Workflow

Rachel is writing a paper on health policy reform.

# 1. Find all active health Acts
nzlegislation search --query "health" --type act --status in-force

# 2. Export for analysis in Excel
nzlegislation export --query "health" --type act --output health_acts.csv

# 3. Get details on a specific Act
nzlegislation get "act/2020/67"

# 4. Generate citation for her paper
nzlegislation cite "act/2020/67" --style nzmj

Example 2: Developer Dan's Integration

Dan is building a research dashboard.

# Get data in JSON format for his app
nzlegislation search --query "health" --format json --limit 100

# Parse in Node.js:
const results = JSON.parse(output);
console.log(`Found ${results.total} results`);

Example 3: Student Sam's Assignment

Sam needs legislation for a coursework essay.

# Search for the Mental Health Act
nzlegislation search --query "Mental Health Act" --type act

# Get the full details
nzlegislation get "act/1992/100"

# Generate APA citation for the bibliography
nzlegislation cite "act/1992/100" --style apa

Example 4: Administrator Alex's Team Setup

Alex is deploying for a research team.

# Install on shared server
npm install -g nz-legislation-tool

# Configure API key for the team
nzlegislation config --key $TEAM_API_KEY

# Test it works
nzlegislation search --query "test" --limit 1

# Set up monitoring (check rate limits)
nzlegislation config --show

🎨 Output Formats

Table Format (Default)

Beautiful, readable tables right in your terminal:

┌────────────────────┬──────────────────────────────────────────┬────────┬──────────┬────────────┐
│ ID                 │ Title                                    │ Type   │ Status   │ Date       │
├────────────────────┼──────────────────────────────────────────┼────────┼──────────┼────────────┤
│ act/2020/67        │ Health Act 2020                          │ act    │ in-force │ 2020-11-15 │
│ act/1956/65        │ Health Act 1956                          │ act    │ repealed │ 1956-10-01 │
└────────────────────┴──────────────────────────────────────────┴────────┴──────────┴────────────┘

JSON Format

For developers and automation:

{
  "total": 42,
  "offset": 0,
  "limit": 25,
  "results": [
    {
      "id": "act/2020/67",
      "title": "Health Act 2020",
      "type": "act",
      "status": "in-force",
      "date": "2020-11-15"
    }
  ]
}

CSV Format

Ready for Excel, R, Python, or SPSS:

id,title,shortTitle,type,status,date,url,versionCount
act/2020/67,Health Act 2020,Health Act 2020,act,in-force,2020-11-15,https://api.legislation.govt.nz/v0/works/act/2020/67,5

⚠️ Rate Limits

The NZ Legislation API has fair use limits:

Limit	Value	Reset
Daily	10,000 requests	Midnight local time
Burst	2,000 requests per 5 minutes	Rolling window

Don't worry—the CLI automatically handles rate limiting. If you hit a limit, you'll see a friendly message telling you when to try again.

🐛 Troubleshooting

"API key not configured"

Quick fix:

nzlegislation config --key YOUR_API_KEY

Still not working? Check if it's set correctly:

nzlegislation config --show

"Authentication failed"

Common causes:

Typo in the API key
API key expired
Wrong key copied

Fix it:

Check your email for the original API key
Re-run: nzlegislation config --key YOUR_KEY
Test: nzlegislation search --query "test"

"Rate limit exceeded"

What happened: You've made too many requests too quickly.

Fix it:

Wait 5 minutes for the burst limit to reset
Or wait until midnight for the daily limit to reset

Prevent it:

Add pauses between bulk requests
Use --limit to reduce batch sizes

"Resource not found"

Common causes:

Wrong ID format (should be like act/2020/67)
The legislation doesn't exist

Fix it:

Search first to find the correct ID:

nzlegislation search --query "health"

Copy the exact ID from results
Try again with the correct ID

"Network error" or "Timeout"

What happened: Can't connect to the API.

Fix it:

Check your internet connection
Try the API website directly: https://api.legislation.govt.nz
If the API is down, wait and try again later

Still stuck? Check the API status or contact support.

📦 Installation Options

Option 1: npm (Recommended for regular use)

npm install -g nz-legislation-tool

Pros: Use anywhere, no need to type npx
Cons: Takes up disk space (~50MB)

Option 2: npx (Try before installing)

npx nz-legislation-tool search --query "health"

Pros: No installation, try before committing
Cons: Slower (downloads each time), need to type npx

Option 3: From Source (For contributors)

git clone https://github.com/edithatogo/nz-legislation-tool
cd nz-legislation-tool
npm install
npm run build
npm link  # Install globally

Pros: Latest features, can contribute changes
Cons: Requires build step, for advanced users

🤝 Contributing

We'd love your help! This project is open source and welcomes contributions from everyone.

Ways to contribute:

🐛 Report bugs
💡 Suggest features
📝 Improve documentation
💻 Submit code fixes

See CONTRIBUTING.md for how to get started.

Quick Development Setup

# Clone the repo
git clone https://github.com/edithatogo/nz-legislation-tool
cd nz-legislation-tool

# Install dependencies
npm install

# Run in development mode
npm run dev -- search --query "health"

# Run tests
npm test

📚 Documentation

Need more help? Check out these guides:

User Guide - Detailed command reference
FAQ - Common questions answered
Troubleshooting - Step-by-step fixes
Developer Guide - For contributors
API Reference - Technical details

🤖 Automation & Maintenance

This repository runs itself with minimal manual intervention:

Automation	Frequency	What It Does
🔒 Security Audit	Weekly	Scans for vulnerabilities
✨ Code Quality	Every commit	Linting, type checking
📦 Dependency Updates	Weekly	Auto-updates safe packages
🧪 Tests	Every commit	43+ automated tests
⚡ Benchmarks	Weekly	Performance tracking
🗑️ Stale Cleanup	Daily	Closes inactive issues

Manual maintenance: ~0 hours/month ✅

See MAINTENANCE_GUIDE.md for details.

🙏 Acknowledgments

NZ Legislation API team (Parliamentary Counsel Office) for providing the API
Victoria University of Wellington for research support
All contributors who make this project better

📬 Support

Need help? We're here for you.

🐛 Found a bug? Open an issue
💬 Have a question? Start a discussion
📧 Email: dylan.mordaunt@vuw.ac.nz
📖 API docs: https://api.legislation.govt.nz/docs/

Response time: We aim to respond within 2 business days.

📄 License

Apache License 2.0 - See LICENSE for details.

TL;DR: Free to use, modify, and distribute. Just give credit and don't hold us liable.

Built with ❤️ for New Zealand researchers, by researchers.

npm · GitHub · API Docs · Documentation

NZ Legislation Tool API - v1.2.0

NZ Legislation Tool

📦 Package Registries

🚪 Choose Your Interface

CLI

MCP Server

✨ What You Can Do

🚀 Quick Start (5 Minutes)

Step 1: Get Your API Key (2 minutes)

Step 2: Install the Tool (1 minute)

Step 3: Set Your API Key (1 minute)

Step 4: Your First Search (30 seconds)

📋 What You Need

📖 Commands (With Examples)

search - Find Legislation

get - View Specific Legislation

export - Download Results to File

cite - Generate Citations

config - Manage Settings

🎯 Real-World Examples

Example 1: Researcher Rachel's Workflow

Example 2: Developer Dan's Integration

Example 3: Student Sam's Assignment

Example 4: Administrator Alex's Team Setup

🎨 Output Formats

Table Format (Default)

JSON Format

CSV Format

⚠️ Rate Limits

🐛 Troubleshooting

"API key not configured"

"Authentication failed"

"Rate limit exceeded"

"Resource not found"

"Network error" or "Timeout"

📦 Installation Options

Option 1: npm (Recommended for regular use)

Option 2: npx (Try before installing)

Option 3: From Source (For contributors)

🤝 Contributing

Quick Development Setup

📚 Documentation

🤖 Automation & Maintenance

🙏 Acknowledgments

📬 Support

📄 License

Settings

On This Page

`search` - Find Legislation

`get` - View Specific Legislation

`export` - Download Results to File

`cite` - Generate Citations

`config` - Manage Settings