nz-libraries git:20260719.1748a98A

Immutable. This exact content never changes and is served at /api/v1/blob/63a683ebe6d434ae.

---
name: nz-libraries
description: "Query selected New Zealand public library catalogues, branch locations, hours, book details, and public availability through a lightweight read-only CLI. Use when the task involves finding books in major NZ public library networks or checking which branches currently show copies."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "public-data"
  thecolab.source_owner: "Participating New Zealand public libraries"
  thecolab.source_type: "mixed"
  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://www.aucklandlibraries.govt.nz/"
  thecolab.allowed_domains: "ap.iiivega.com,catalogue.wcl.govt.nz,christchurch.bibliocommons.com,christchurchcitylibraries.com,discover.aucklandlibraries.govt.nz,ent.kotui.org.nz,hamiltonlibraries.co.nz,library.tauranga.govt.nz,www.aucklandlibraries.govt.nz,www.dunedinlibraries.govt.nz,www.wcl.govt.nz"
  thecolab.last_verified: "2026-07-19"
  thecolab.health: "healthy"
  thecolab.maintainer: "@adam91holt"
---

# NZ Libraries

## Goal

Query live public catalogue and branch data for major New Zealand public library networks through a small deterministic CLI with human-readable and JSON output, without browser automation, login, holds, or account actions.

Catalogue search is the primary feature. Branch locations and hours are wired where the public site exposes a stable no-login page.

## Use this when

- A user asks whether a book is held by Auckland, Wellington, Christchurch, Hamilton, Dunedin, or Tauranga public libraries
- A user wants public branch-level availability where the catalogue exposes it
- A user wants branch names, addresses, opening hours, contact details, or facilities for supported branch-hour pages
- A workflow needs machine-readable public catalogue results from NZ library networks
- A user needs a fast read-only alternative to manually opening several library catalogues

## Do not use this for

- Holds, reservations, renewals, checkouts, fines, borrower records, saved lists, login, or account actions
- Authenticated catalogue views or patron-specific availability
- High-volume harvesting, dataset redistribution, or bypassing rate limits
- Libraries outside the supported networks unless the CLI has been extended and verified

## Preferred workflow

1. Run `scripts/cli.py networks` to confirm the currently wired networks and limitations
2. Use `search <query> --network <key>` for the narrowest catalogue lookup
3. Use `book <id>` with an id returned by `search` for public bib/detail fields
4. Use `availability <id>` for branch/copy information where the backend exposes it
5. Use `branches`, `branch`, or `hours` for branch pages where public hours are wired
6. Use `--json` for agent chaining, comparisons, alerts, or structured reports

## CLI

Run with:

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

## Commands

- `networks [--json]` - list supported networks, backends, and branch-hours support
- `branches [--network auckland|wellington|christchurch|hamilton|dunedin|tauranga] [--json]` - list wired branch locations and hours
- `branch <name> [--network key] [--json]` - show one branch by fuzzy name
- `search <query> [--network key] [--limit N] [--json]` - search one or all supported catalogues
- `book <id> [--network key] [--json]` - fetch public book/bib detail
- `availability <book-id> [--network key] [--json]` - show public availability/copy information
- `hours [--network key] [--json]` - list opening hours for wired branch-hour networks

## Examples

```bash
python3 skills/nz-libraries/scripts/cli.py networks
python3 skills/nz-libraries/scripts/cli.py search "Eleanor Catton" --network auckland --limit 5 --json
python3 skills/nz-libraries/scripts/cli.py search "Pip Adam" --network christchurch --limit 5
python3 skills/nz-libraries/scripts/cli.py branches --network wellington --json
python3 skills/nz-libraries/scripts/cli.py hours --network christchurch --json
python3 skills/nz-libraries/scripts/cli.py availability auckland:3b4b3224-44e2-5e5d-a627-823679741a24 --json
```

## Resources

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

## Notes

- Supported networks: Auckland Libraries (`aucklandlibraries.govt.nz`, `discover.aucklandlibraries.govt.nz`), Wellington City Libraries (`wcl.govt.nz`, `catalogue.wcl.govt.nz`), Christchurch City Libraries (`christchurchcitylibraries.com`, `christchurch.bibliocommons.com`), Hamilton City Libraries (`hamiltonlibraries.co.nz`, `ent.kotui.org.nz/client/en_AU/hamilton`), Dunedin Public Libraries (`dunedinlibraries.govt.nz`, `ent.kotui.org.nz/client/en_AU/dunedin`), and Tauranga City Libraries (`library.tauranga.govt.nz`, `ent.kotui.org.nz/client/en_AU/tauranga`)
- Auckland catalogue search, detail, and physical branch availability use public Vega endpoints; Auckland branch hours come from the public locations-and-services page
- Wellington catalogue search and availability use public Spydus HTML/XHLD pages; Wellington branch hours come from public WCL branch pages
- Christchurch catalogue search and detail use BiblioCommons server-rendered JSON; Christchurch branch hours come from the public BiblioCommons locations fragment
- Hamilton, Dunedin, and Tauranga catalogue search use public Kotui/SirsiDynix Enterprise search pages; branch-hours pages are not wired in this lightweight version
- No API key, username, password, account cookie, browser session, or write action is required
- Endpoint shapes can change without notice because these are unofficial public website surfaces