canonical: https://jentic.com/apis/digitalnz.org/digitalnz

# DigitalNZ API

DigitalNZ aggregates over 30 million records from New Zealand's libraries, museums, archives, and public broadcasters into a single searchable index. The Records API exposes that index over three GET endpoints: full-text and faceted search, single-record retrieval, and a more-like-this similarity query. It is widely used by educators, researchers, journalists, and cultural-heritage projects to embed verified Aotearoa source material into apps and AI workflows.

## For AI agents

Search and retrieve over 30 million records of New Zealand cultural and historical material - images, documents, audio, and video - by keyword, facet, or similarity. Useful for research, cultural-heritage and educational agents.

## Scope

Does not host the original media files, mediate copyright licensing, or expose write/upload operations - use for searching and retrieving aggregated NZ heritage record metadata only.

## Capabilities

- Run keyword and faceted searches across 30M+ NZ heritage records via /records.{format}
- Retrieve a single record's full metadata and source links via `/records/{record_id}.{format}`
- Discover related items for a given record using `/records/{record_id}/more_like_this.{format}`
- Filter searches by content_partner, primary_collection, category, copyright, year, and language facets
- Return results as JSON, XML, or RSS by setting the format path parameter

## Use cases

### Cultural Heritage Research and Education

Researchers, teachers, and students can build classroom resources and academic projects on top of DigitalNZ's aggregated index of New Zealand archives, libraries, and museum collections. The /records.{format} endpoint supports keyword and faceted search, returning rich metadata and source links so users can cite and link back to the originating institution. Free API access combined with permissive Creative Commons filtering makes it suitable for open educational resources.

Example prompt: Call /records.json with a query of 'Treaty of Waitangi' filtered to primary_collection=Te Papa and return the top 10 records with title, thumbnail, and source URL.

### Embedding NZ Source Material in Newsrooms and Blogs

Journalists and content sites can pull verified historical photographs, documents, and recordings into articles by querying DigitalNZ for relevant records and rendering thumbnails with attribution. The more_like_this endpoint suggests related material to deepen storytelling. Because results include rights metadata, editorial teams can filter to clearly licensed content before publication.

Example prompt: Search DigitalNZ for 'Christchurch earthquake 1931' filtered to copyright='No known copyright restrictions' and return image URLs with attribution strings.

### Building Recommendation Surfaces for Cultural Apps

Cultural app developers can power 'see also' panels by calling `/records/{record_id}/more_like_this.json` after a user opens a record. DigitalNZ scores similarity using shared metadata facets such as primary collection and subject. This reduces development time compared with building an in-house similarity engine and keeps recommendations grounded in curated heritage data.

Example prompt: For DigitalNZ record_id 12345, call `/records/12345/more_like_this.json` and return the top five similar records with their titles and primary collection.

### AI Agent Heritage Research Assistant

AI agents can act as research assistants for New Zealand history and culture by calling DigitalNZ through Jentic. Agents combine the search and more-like-this operations to gather primary sources, then summarise findings with citations. Jentic isolates the API key in your Jentic One instance so the agent never sees the raw token.

Example prompt: Search Jentic for 'search New Zealand archives', load the DigitalNZ records.json operation, and execute it with the query 'Suffrage petition 1893' to gather primary-source records for a research summary.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/records.{format}` | Search the aggregated DigitalNZ index with keywords and facets |
| GET | `/records/{record_id}.{format}` | Retrieve a single record by ID |
| GET | `/records/{record_id}/more_like_this.{format}` | Find records similar to a given record |

## Key resources

- **Records** — Search, retrieve, and find similar New Zealand heritage records across 200+ contributing institutions

## Why Jentic

- **Setup:** Wiring DigitalNZ by hand means passing its api_key query parameter, choosing the response format, and paging aggregated heritage records yourself. Through Jentic you install once, import the DigitalNZ API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** DigitalNZ is a read-only search surface, so scope your agent to the operations it needs, such as searching records or fetching similar records. You choose the operations it may call, so single-record retrieval is not included unless you add it.
- **Credential handling:** Your DigitalNZ API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search New Zealand archives' or 'find similar heritage records', and Jentic returns the matching DigitalNZ operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **data.gov** — US government open data catalog with cultural and statistical datasets
- **Internet Archive Search** — Global open archive of texts, images, audio, and video
- **MusicBrainz** — Open music metadata database

## FAQ

### What authentication does the DigitalNZ API use?

It uses an API key passed via the api_key query parameter on every request. Keys are issued free from digitalnz.org/developers. Through Jentic, the key is stored encrypted in your Jentic One instance and injected at execution time, so agents never need to handle the raw key.

### Can I find similar records to a given item with the DigitalNZ API?

Yes, call `/records/{record_id}/more_like_this.{format}` with the record's ID and the desired response format (json, xml, or rss). DigitalNZ returns records that share metadata signals such as primary collection, subject, and content type.

### What are the rate limits for the DigitalNZ API?

DigitalNZ does not publish a hard rate limit in the OpenAPI spec. Their developer guidelines ask for considerate usage and contact for high-volume needs. For production traffic, register your application and request a higher tier through the digitalnz.org/developers contact form.

### How do I search DigitalNZ records through Jentic?

Search Jentic for 'search New Zealand archives', load the schema for the /records.{format} operation, and execute it with your text query and any facet filters such as content_partner or primary_collection. Jentic returns the JSON record list with titles, sources, and rights metadata.

### Is the DigitalNZ API free?

Yes, the DigitalNZ Records API is free for non-commercial use with attribution. Commercial use requires contacting the DigitalNZ team through the developer portal to discuss licensing of contributing institutions' content.

### Can I limit what my agent is allowed to do with the DigitalNZ API?

Yes. Because Jentic One is self-hosted, you set the rules for which DigitalNZ operations and credentials your agent may use. The DigitalNZ API is a read-only search surface, so you can scope the agent to just the operations it needs, such as searching records at /records.{format} or finding similar records at `/records/{record_id}/more_like_this.{format}`, while leaving single-record retrieval at `/records/{record_id}.{format}` unavailable unless you add it. Your API key stays in your own Jentic One instance and is injected only when a permitted operation runs.