Api Docs v3

The current DigitalNZ API is version 3.

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

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 DigitalNZ 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 anonymised usage 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.