Accessing the DigitalNZ API

Posted on 13 December 2021 by James Robertson

We have recently made two changes to the way people authenticate with the DigitalNZ API.

Photo of an old key.

Image from Te Papa (AR000627/568). CC BY-NC-ND.

Keyless entry

The first, and hopefully the most  impactful change, was to remove the requirement for an API key (secret ID) to access public data. This means that anyone can query our API and retrieve structured, open data for individual records or a collection of records (search).

We hope that this change will further lower the barrier to reuse of the data we collect, making it easier still for Digital Humanities researchers, and other curious bods, who want to ‘play’ with the API and discover its value to them. This in turn may encourage more people to dig deeper and possibly even develop new applications or websites to utilise the data.

Try it for yourself! (You’ll enjoy the experience much more in Firefox, which will present the results in a friendly fashion.)

Keys for busy users

However, a maximum query rate limit applies across all unauthenticated public requests. This rate limit is in place to protect the service from overuse, resulting in unsustainable costs, or potential attack. So, API keys are still available for use by regular, high volume consumers, or application developers, so that we can:

  • provide targeted help and support

  • increase query throughput (by negotiation)

  • notify of changes to the API

  • gather usage metrics to help improve the service.

Keeping keys secret

Which brings us to the second change we have made; passing API keys in the HTTP header instead of the request URL. This change improves the security and confidentiality of the API key transfer process. You can learn more about this change in API docs v3.

For now, we still support keys passed in the request URL. However, we plan to deprecate this feature in the middle of 2022. In the meantime, we will be doing our best to contact any affected users and help them transition to passing their key in the custom HTTP header, ‘Authentication-Token’.

Learn more

For more information about these changes, and our API in general, please see the Developers section of our website. And, as always, if you have any questions or feedback, please don’t hesitate to email us at

We've turned off comments here, but we'd still love to know your thoughts. Visit us on our Facebook Page @digitalnz or on Twitter @DigitalNZ to share any ideas or musings with the DigitalNZ team.