Sign in

v1

latestOpenAPI 3.0.12026-07-133126.1 KB
API calls

View metadata associated with a single record.

If you know its record_id you can use this endpoint to view all metadata associated with that specific record.

get/records/{record_id}.{format}

Path parameters

record_idinteger required

Every record has a unique, persistent record_id.

format'json' | 'xml' required

Note - There is a small difference with some field names in the response between JSON and XML.
When a field name has more than one word, JSON format will separate the words with an underscore, eg. "content_partner", whereas XML uses a hyphenated naming convention, eg. "content-partner".

Query parameters

fieldsstring

Comma-separated whitelist of fields to be returned. The syntax "&fields=verbose" can be used to return the bulk of the fields, or you can customise which fields you are interested in, eg. "&fields=id,title,subject,collection,landing_url,locations".

Headers

Authentication-Tokenstring

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 metrics to help improve the service

API requests that do not pass a valid API key/token 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 username drop-down menu (on the right hand side)'. 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: ‘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

Response

ok

idinteger

All records have a unique identifier used within the DigitalNZ system.

created_atstring date-time

The date the record was initially harvested into DigitalNZ.

updated_atstring date-time

The date the record was last updated/re-harvested into DigitalNZ.

titlestring

Title of the record. All records should have a title.

descriptionstring

Description of the record. Most records have a description.

content_partnerstring[]

Name of the organisation(s), institution(s), or individual(s) making content available through DigitalNZ. This metadata will be present on all records and is usually the name of the organisation that has agreed to the DigitalNZ Metadata Contribution Terms.

display_content_partnerstring

The main Content Partner, for cases when there are more than one. This metadata will be present on all records.

display_collectionstring

The single main collection or website that the item belongs to. This metadata will be present on all records.

primary_collectionstring[]

In most cases this is the same as display_collection, but will occasionally a second value.

collectionstring[]

In addition to the top level "display_collection" above, this field can also contain sub-collections or groupings within the main collection.

collection_titlestring[]

For historic reasons this is a duplicate of the previous field ("collection").

categorystring[]

There will always be at least 1 human-readable category label in this field.

creatorstring[]

The name's of the people, organisations, institutions, services etc. who created the content (eg. the photographer, artist, writer or author).

subjectstring[]

Keywords about the content.

dc_identifierstring[]

Identifiers relating to the content from the content partner's system.

datestring[]

Date information associated with this record (e.g. 1996-01-01T00:00:00.000Z). This field may be empty.

display_datestring

Where provided, this field contains a human readable version of the date information.

landing_urlstring

This field will always contain a URL of the item on the content partner's website.
Note: Please use the source_url when providing HTML links.

source_urlstring

This URL will always be present and provides a redirect to the landing_url. This link should be used as the main click-through to the content. Passing users through this link allows DNZ to count the number of click-throughs, as well as trigger link-checking activities that help clean up stale links in DigitalNZ.

thumbnail_urlstring

URL for a thumbnail image of the content. The size varies depending on what is available but we aim for a width of 250px. This field is mostly populated on records with a 'category' of 'Images', but is also sometimes found on others (eg. "Videos").

large_thumbnail_urlstring

URL for a larger thumbnail image with a width of up to 800px. NOTE - the API Terms do not extend rights to the use of images accessable throught the large_thumbnail_url field.

usagestring[]

This field is always present and contains human-understandable information about how the item may be used based on its copyright/license.

copyrightstring[]

A copyright statement applying to the object referenced by this record. This field may be empty.

rightsstring

Rights information. Can be a rights statement explaining the rights of the record or a link to a webpage with more detailed rights information.

rights_urlstring[]

An array of HTTP URLs resolving to a rights statement or terms of use information for the resource.

Example response

{
  "id": 1788754,
  "created_at": "2012-04-21T05:32:02.000+13:00",
  "updated_at": "2020-12-06T01:36:37.359+13:00",
  "title": "Election night crowd, Wellington, 1931",
  "display_date": "Circa 1996",
  "source_url": "https://api.digitalnz.org/records/1788754/source",
  "locations": [
    {
      "lat": -37.508219086,
      "lng": 177.1802173,
      "placename": "White Island",
      "comment": "Location provided by the Alexander Turnbull Library"
    }
  ]
}