Records (Search)

Method: GET
Availability: Available since version 1
History: Query parameters and response formats significantly changed in version 3. Versions 1 and 2 are no longer supported.

The Search Records API call returns a result set in response to a search query.

URL format

http://api.digitalnz.org/<version>/records.<response_format>?<request_parameters>

Request parameters, required

The following must be specified as request parameters:

http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=cat+dog

Request parameters, optional

The following may be specified as request parameters:

Response format

In version 3 the search records and get metadata call response elements have been standardised. Appending an extension to a resource tells the API to use the requested format. Valid extensions are: xml, json and rss. Examples:
http://api.digitalnz.org/v3/records.xml?api_key=<your_api_key>&text=cat+dog
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=cat+dog
http://api.digitalnz.org/v3/records.rss?api_key=<your_api_key>&text=cat+dog

Note: Responses in XML format will return field names in a hyphenated format. For example; "content_partner" in an XML format will look like: <content-partner>Kete Horowhenua</content-partner>

Response elements

The search results will return the following elements:

A note on facets

Faceted search is a user interface technique for helping users to refine their searches by prompting them with metadata elements to add to their search. The Wikipedia faceted search page provides useful background information.

DigitalNZ can calculate facet values for any search. In the DigitalNZ search interface these facets are used to filter and categorise search results.

The facets that you can request through the DigitalNZ search records API are category, display_collection, creator, placename, year, decade, century, language, content_partner, rights, collection.

Commercial Use Metadata

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.

For example, to search for results relating to Auckland that are available for commercial use you would use this query:
http://api.digitalnz.org/records.json?api_key=<your_api_key>&and[is_commercial_use]=True&text=Auckland

Examples

Search for 'social welfare' and return only ten results per page, starting at page three:
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=social+welfare&per_page=10&page=3

Search for 'social welfare' and only return the title, content_partner, creator and display_collection fields:
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=social+welfare&fields=title,content_partner,creator,display_collection

Search for Kete Horowhenua for images with the term 'hangi':
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=hangi&and[content_partner][]=Kete+Horowhenua&and[category][]=Images

Give me result counts for the search term 'health' broken down by top 20 content partners, without showing me the actual records:
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&text=health&per_page=0&facets=content_partner&facets_per_page=20

Search for Wellington region for the term "kiwi":
http://api.digitalnz.org/v3/records.json?api_key=<your_api_key>&geo_bbox=-41,174,-42,175&text=kiwi