Sign in

v1

latestOpenAPI 3.0.12026-07-133126.1 KB
API calls

Run queries against DigitalNZ metadata search service.

This is the main search endpoint allowing queries against the records database.

get/records.{format}

Path parameters

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

textstring

This field enables queries based on one or more search terms and provides the functionality of the main search box on digitalnz.org. Search terms can be combined with boolean operators (AND, OR).
A minus sign excludes certain terms, eg. "-horse".
An asterisk (*) acts as a wildcard, eg. "ted*".
Multiple search terms are combined with an AND by default.
Examples: "moustache", "Wanganui OR Whanganui", "-paperspast", "ted*"

and[category][]'Newspapers' | 'Images' | 'Books' | 'Articles' | 'Journals' | 'Archives' | 'Audio' | 'Other' | 'Manuscripts' | 'Reference sources' | 'Research papers' | 'Videos' | 'Music Score' | 'Groups' | 'Data' | 'Websites' | 'Sets'

These are the same categories that are used across the tabs in digitalnz.org

and[content_partner][]string

Allows filtering for records from a particular Content Partner.
Examples: "Ministry for Culture and Heritage" "Trove" "V.C. Browne & Son"

Tip - To see a list of Content Partners available for filtering use the facets parameter, eg. "&facets=content_partner".

and[primary_collection][]string

Allows filtering for records from a particular primary_collection.
Examples: "Puke Ariki" "NZHistory" "TAPUHI"

Tip - To see a list of Primary_Collections available for filtering use the facets parameter, eg. "&facets=primary_collection".

and[collection][]string

Allows filtering for records from a particular Collection. Collections can be thought of as sub-collections or groupings under Primary_Collections.
Examples: "Music 101" "Mollusks" "Wairarapa Daily Times"

Tip - To see a list of Collections available for filtering use the facets parameter, eg. "&facets=collection".

and[usage][]'Share' | 'Modify' | 'Use commercially' | 'All rights reserved' | 'Unknown'
and[subject][]string

Examples: "Cats" "Weddings" "climb*"

and[dc_type][]string

Examples: "Conference item" "Magazines"

and[format][]string

Examples: "Photolithographs" "Glass*"

and[placename][]string

This field can be used for text-based location search. For a more advanced coordinate-based search, see the "geo_bbox" field below.
Examples: "Scott Base" "Wainuiomata" "castle*"

and[creator][]string

Examples: "Revelle Jackson" "Nicholas Chevalier" "Rita Angus"

and[title][]string

Examples: "Pukeko" "Club" "Break*""

and[date]string

This field can be useful for querying and sorting (see the 'sort' param further down). But it should be noted that, as with some other fields, not all records have date metadata associated. There is good coverage of date metadata within certain collections, but there are plenty with no date information at all. So, if you query for records from a specific date you may get some matching results, but might also be missing other potentially relevant records that don't have date metadata available.
Example: "1970-12-25"

Tip - There is a related (but not searchable) field that is returned on each record (where available), that often has a more human readable version of the date information, called 'display_date'.

and[year]string

This field allows searching specifically by year. The metadata is derived from the same date information that is searchable and returned in the date field. It is possible to search across a range using syntax the following syntax [{start year} TO {end year}].
Example: "1893" "[1982 TO 1987]"

and[decade]string

This field allows searching specifically by decade. The metadata is derived from the same date information that is searchable and returned in the date field.
Example: "1850" "1990"

and[century]string

This field allows searching specifically by century. The metadata is derived from the same date information that is searchable and returned in the date field.
Example: "1900" "2000"

without[{filter_field}]string

All of the above and[___][] filters in this document are also able to be used with this syntax to exclude specific matches. For example to exclude Papers Past content &without[primary_collection]=Papers+Past

and[or][{filter_field}][]string

All of the above and[___][] filters in this document are also able to be used with the and[or][___][] syntax to allow multi-select OR queries within one field.
Basic example:

  • To filter your results to only those with a category or Audio or Videos:
    &and[or][category][]=Audio&and[or][category][]=Videos

In order to combine OR filters across multiple fields the syntax needs to be nested as follows
Nested examples:

  • To search for (year is 2014 OR 2015) AND (primary_collection is TAPUHI OR Public Address)
    &and[or][year][]=2015&and[or][year][]=2014&and[and][or][primary_collection][]=TAPUHI&and[and][or][primary_collection][]=Public+Address
  • To search for (category is Images OR Video) AND (subject is cat OR cats)
    &and[or][category][]=Images&and[or][category][]=Videos&and[and][or][subject][]=cat&and[and][or][subject][]=cats
and[is_commercial_use]boolean

Some DigitalNZ partners offer their metadata for use in commercial applications. This content can be identified through the is_commercial_use flag. Only API results where the is_commercial_use field set to True can be used for commercial purposes. Check out the terms of use for more information.

and[has_large_thumbnail_url]'Y'

Filters results to only those records that have an image available in the large_thumbnail_url field.
Note: There is an issue with this field where, in order to get results, it needs to be specified with "Y" or not specified at all.

and[has_lat_lng]true | false

Filters results to only those records that have latitude and longitude coordinates present in the metadata.

Tip - To see the location metadata you'll need to specifically request that field using the fields parameter - "&fields=verbose,locations" as it is not part of the default, or verbose field sets.

geo_bboxstring

A geographic bounding box scoping a search to a geographic region. Order of latitude-longitude coordinates is north, west, south, east. For example, filtering the Wellington region would be "&geo_bbox=-41,174,-42,175"

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".

sort'syndication_date' | 'date'

Used to control the order of the results in conjunction with the direction field.

  • syndication_date - is the creation date of the record within DigitalNZ, ie. when DigitalNZ first harvested the record.
  • date - is the date metadata (if present) associated with the record.

To sort the search results with newest records at the top use: "&sort=syndication_date&direction=desc"

direction'asc' | 'desc'

Used in conjunction with sort to order the results

  • asc - Ascending, oldest first.
  • desc - Descending, newest first.
pageinteger

Specify which page of results to return.

per_pageinteger

The number of records to return per page of search results.

facetsstring[]

Shows a breakdown of record counts for the specified facets based on the current result set. In the DigitalNZ search interface these facets are used to list the values filterable for each field. A comma-separated list will return multiple facets in one call.

facets_pageinteger

This value specifies which page of facet results to return. Allowing pagination through large lists of facet values.

facets_per_pageinteger

The number of facets to return per page of facet results.

exclude_filters_from_facetsboolean

This field can be used when filtering into some facets, to maintain the context of the wider facet values. A common use case is to allow the results of a search to be filtered down into a specific category (eg Audio), while still showing the other possible filter options as facet counts (eg. Images, Audio, Video, etc). Setting this to 'true' will not effect the search results returned but will ignore all search filters (eg. "and[category]=Audio") when calculating the facet counts.

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

search results matching criteria

result_countinteger

Total number of matching search results.

pageinteger

Current page.

per_pageinteger

Requested amount of records shown per page of results.

request_urlstring

The URL of current page of results.

facetsobject

Each field you request from the list of facetable fields will be returned as separate elements. Each of those will contain a sorted list of elements that are made up of a value (eg collection name, subject, date) and the number of results associated with that value.

Example response

{
  "result_count": 8190,
  "page": 3,
  "per_page": 20,
  "request_url": "https://api.digitalnz.org/v3/records.json?per_page=10&facets_per_page=100&facets=category&text=Wainuiomata",
  "records": [
    {
      "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"
        }
      ]
    }
  ],
  "facets": {
    "display_collection": {
      "Figure.NZ": 40185,
      "Napier Public Libraries": 39343,
      "Canterbury Museum": 39109
    },
    "year": {
      "1997": 4,
      "1998": 10,
      "1999": 16
    }
  }
}
All 3 operations