API docs v3

The current DigitalNZ API is version 3.

We provide three API calls (endpoints) for accessing the DigitalNZ corpus:

  • Search records to query the DigitalNZ metadata search service
  • Get metadata for a specific record
  • Sets for returning data from your virtual Set collections

Remember that DigitalNZ does not have a copy of items in the collection. Instead, we hold metadata about items in other collections, together with a pointer to the content object. digitalnz.org therefore behaves much like a search engine.

The Metadata Dictionary provides further detail about the common fields used in the Digital New Zealand harvesting system.

Detail on the API parameters

For more detail about the API parameters and responses, please see the DigitalNZ OpenAPI spec on SwaggerHub.

API keys

The DigitalNZ API no longer requires a key to access public content. However, if you plan on using the API regularly, expect to be a high volume consumer or are planning on creating an application, we encourage you to use an API key so that we can:
  • provide targeted help and support
  • increase your query throughput (by negotiation)
  • notify you directly of changes to the API
  • gather usage anonymised metrics to help improve the service.

API requests that do not pass a valid API key are treated as unauthenticated. A maximum rate limit applies across all unauthenticated requests. This rate limit is in place to protect the service from overuse, resulting in unsustainable costs, or potential attack.

Getting an API key

Create a DigitalNZ account, log in and select "my API key" from your right-hand drop-down menu. The key is a long string of jumbled letters and numbers (hash) that is unique to you. You are required to keep the key secret. (Refer to the Developer API Terms of Use for more information).

Using an API key

When you make a call to the API you'll need to pass the key in a custom HTTP header called ‘Authentication-Token’.
For example, a query using the ‘curl’ command might look like the following (where ‘{YOUR_API_KEY}’ is replaced with a valid API key):

curl -H "Authentication-Token:{YOUR_API_KEY}" http://api.digitalnz.org/v3/records.json?text=kiwi

Terms of use

Please be sure to read the Developer API Terms of Use to learn how you are allowed to use the metadata.