GET /records.{format}

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](https://digitalnz.org/sign_up), log in and select "[my API key](https://digitalnz.org/api_keys/edit)" 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](https://digitalnz.org/about/terms-of-use/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`

These are the same categories that are used across the tabs in [digitalnz.org](https://digitalnz.org/records?text=&tab=Videos)

Constraints: {'enum': ['Newspapers', 'Images', 'Books', 'Articles', 'Journals', 'Archives', 'Audio', 'Other', 'Manuscripts', 'Reference sources', 'Research papers', 'Videos', 'Music Score', 'Groups', 'Data', 'Websites', 'Sets']}

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

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

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

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

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

Examples: `"Conference item"` `"Magazines"`

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

Examples: `"Photolithographs"` `"Glass*"`

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.

Constraints: {'enum': ['Y']}

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.

Constraints: {'enum': [True, False]}

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](https://digitalnz.org/about/terms-of-use/developer-api-terms-of-use#commercial_use_terms) for more information.

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`

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*"`

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

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

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

Constraints: {'enum': ['Share', 'Modify', 'Use commercially', 'All rights reserved', 'Unknown']}

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]"`

Used in conjunction with *sort* to order the results - *asc* - Ascending, oldest first. - *desc* - Descending, newest first.

Constraints: {'enum': ['asc', 'desc']}

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.

Shows a breakdown of record counts for the specified facets based on the current result set. In the [DigitalNZ search interface](https://digitalnz.org/records) these facets are used to list the values filterable for each field. A comma-separated list will return multiple facets in one call.

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

Constraints: {'minimum': 1}

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

Constraints: {'maximum': 350}

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

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

Constraints: {'enum': ['json', 'xml']}

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

Specify which page of results to return.

Constraints: {'minimum': 1}

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

Constraints: {'minimum': 0, 'maximum': 100}

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"

Constraints: {'enum': ['syndication_date', 'date']}

This field enables queries based on one or more search terms and provides the functionality of the main search box on [digitalnz.org](https://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*"`

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`