git:20260523.f7d719e to git:20260719.1748a98

22 added, 1 removed. Audit A to A.

---

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.

+ 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

- `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