nzpost git:20260719.1748a98A

Immutable. This exact content never changes and is served at /api/v1/blob/08257dad7f246f9a.

---
name: nzpost
description: "Query NZ Post public APIs for parcel tracking, PostShop/parcel-collect/postbox location search, and address/postcode lookup. No authentication required. Use when the task involves tracking an NZ Post parcel, finding a nearby PostShop or parcel-collect point, looking up a New Zealand delivery address or postcode, or fetching complete tracking history for a domestic or international tracking number."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "transport"
  thecolab.source_owner: "NZ Post"
  thecolab.source_type: "official"
  thecolab.auth: "none"
  thecolab.access_mode: "public-api"
  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-api"
  thecolab.pack: "nz-public-data"
  thecolab.source_url: "https://tools.nzpost.co.nz/tracking/api"
  thecolab.allowed_domains: "api.nzpost.co.nz,nominatim.openstreetmap.org,tools.nzpost.co.nz,www.nzpost.co.nz"
  thecolab.last_verified: "2026-07-19"
  thecolab.health: "healthy"
  thecolab.maintainer: "@adam91holt"
---

# NZ Post

## Goal

Query NZ Post public APIs for parcel tracking, location search (PostShops, parcel-collect points, postboxes), and address/postcode lookup. No authentication required.

## Use this when

- A user wants to know where their NZ Post parcel is
- A user asks if a parcel has been delivered
- A user wants to see the full tracking history for a shipment
- A user has a domestic NZ Post tracking number or an international inbound tracking number routed through NZ Post
- A user asks "where is my package?" with an NZ Post or CourierPost number
- A user wants to find a PostShop, parcel-collect point, or postbox near a location
- A user wants to look up a New Zealand address or postcode

## Do not use this for

- DHL, FedEx, UPS, or other non-NZ Post carriers
- NZ Post MyMail/standard letters (untracked items)
- Booking or scheduling courier pickups
- Redirecting or modifying delivery instructions

## Preferred workflow

1. Run `track <number>` for a human-readable status summary and event timeline
2. Run `locations --near "SUBURB"` to find nearby NZ Post facilities
3. Run `address "QUERY"` to look up NZ delivery addresses and postcodes
4. Add `--json` to any command for machine-readable output suitable for piping

## CLI

Run with:

```bash
python3 skills/nzpost/scripts/cli.py <command> [flags]
```

### `track`

Track one or more parcels by tracking number.

```bash
# Human-readable output
python3 skills/nzpost/scripts/cli.py track 00794210392715622565

# Machine-readable JSON
python3 skills/nzpost/scripts/cli.py track 00794210392715622565 --json

# Multiple parcels
python3 skills/nzpost/scripts/cli.py track 00794210392715622565 00000000000000000000 --json

# International UPU format
python3 skills/nzpost/scripts/cli.py track EA123456789NZ --json
```

### `locations`

Find PostShops, parcel-collect points, and postboxes near a location.

```bash
# By place name
python3 skills/nzpost/scripts/cli.py locations --near "Clevedon, Auckland" --limit 5

# By coordinates
python3 skills/nzpost/scripts/cli.py locations --lat -36.8485 --lon 174.7633 --limit 10

# By keyword
python3 skills/nzpost/scripts/cli.py locations --keyword "Auckland CBD" --limit 10

# Filter by type
python3 skills/nzpost/scripts/cli.py locations --near "Auckland CBD" --type postshop

# JSON output
python3 skills/nzpost/scripts/cli.py locations --near "Clevedon" --json
```

### `address`

Look up NZ delivery addresses and postcodes.

```bash
# Human-readable list
python3 skills/nzpost/scripts/cli.py address "Papakura" --limit 10

# JSON output
python3 skills/nzpost/scripts/cli.py address "Papakura" --json
```

## Tracking number formats

NZ Post accepts a wide range of tracking number formats:

- 18 or 20 digit domestic numbers (e.g. `00794210392715622565`)
- 13-digit domestic short numbers
- UPU international format: 2 letters + 9 digits + 2 letters (e.g. `EA123456789NZ`)
- Alphanumeric codes (TP, RMA, RMC, SUN, CTC prefixes, etc.)

## Output fields (JSON, track)

| Field | Description |
|-------|-------------|
| `tracking_reference` | The normalised tracking number |
| `status` | Current delivery status label |
| `last_updated` | ISO 8601 UTC timestamp of the latest event |
| `last_depot` | Last known depot name, if available |
| `event_count` | Total number of tracking events |
| `events[]` | Full event timeline, oldest first |
| `events[].date_time` | UTC timestamp |
| `events[].status` | Short status label |
| `events[].description` | Longer description (HTML stripped) |
| `events[].depot_name` | Depot name, if applicable |
| `events[].run_name` | Courier run or area name, if applicable |
| `events[].edifact_code` | Internal EDIFACT event code |

## Resources

- CLI entrypoint: `scripts/cli.py`
- API discovery notes: `references/api-notes.md`

## Notes

- No API key or authentication required
- Tracking endpoint: `tools.nzpost.co.nz/tracking/api/parceltrack/parcels`
- Locations endpoint: `api.nzpost.co.nz/digital/postshop-locations/v2/locations`
- Address endpoint: `tools.nzpost.co.nz/legacy/api/suggest` (requires Referer header)
- Python stdlib only (`urllib`, `json`, `re`, `argparse`)
- Delivered parcels retain their full tracking history indefinitely