Search records API

The search records API call is passed a search query and returns a corresponding result set.

URL format

http://api.digitalnz.org/records/[version].[response_format]/?[request-parameters]

Request parameters

The following must be specified as request parameters:

  • search_text - the text you wish to search for
  • api_key - the developer API key. In the example URLs replace your_api_key with your personal API key

e.g. http://api.digitalnz.org/records/v1.xml/?
search_text=social+welfare&api_key=your_api_key

The following may be specified as request parameters:

  • num_results - the number of results the user wishes returned up to a maximum of 100 results. Defaults to 20.
  • start - the offset from which the result list should start
  • sort - the field upon which results are sorted. If sort_field isn't specified the results are sorted by relevance. The sort_field must be one of: category, content_provider, date, syndication_date, title
  • direction - the direction in which the results are sorted. Can only be used in conjunction with the sort field and must be either asc or desc. If not specified, sort_direction defaults to asc
  • facets - a list of facet fields to include in the output. See the note on facets below for more information.
  • facet_num_results - the number of facet results to include. Only used if the facets parameter is specified, and defaults to 10.
  • facet_start - the offset from which the facet value list should start. Only used if the facets parameter is specified, and defaults to 0.

Note that you may need to encode special characters used in the URL e.g. %2B can replace + in:

http://api.digitalnz.org/records/v1.xml/?
search_text=social+welfare&api_key=your_api_key

Response format

Appending an extension to a resource tells the API to use the requested format. Valid extensions are xml, json, rss.

You can also specify the format in the Accept header of the HTTP request, e.g. Accept: application/json in a request to http://api.digitalnz.org/records/v1/ tells the API to use JSON format. Valid Accept headers include application/json, application/js, application/xml, application/rss+xml

e.g. http://api.digitalnz.org/records/v1.xml/?
search_text=social+welfare&api_key=your_api_key

e.g. http://api.digitalnz.org/records/v1.json/?
search_text=social+welfare&api_key=your_api_key

Response elements

The search results will return the following elements:

  • num_results_requested - the value of the num_results parameter sent to the API method
  • result_count - the total number of results matching this search
  • start - the value of the start parameter sent to the API method
  • results - the search results data. The results element will contain 0 or more result elements, each containing the following elements:

category - a string containing one or more category names separated by a comma (e.g. Images, Web pages)
content_provider - the institution holding the content to which the record refers
date - a date associated with the record (e.g. 1996-01-01T00:00:00.000Z). This field may be empty
description - text describing the record
display_url - the url for the content on the content provider's website. Please use the source-url when providing HTML links (see below)
id - the internal DigitalNZ identifier (used by the Get Metadata API)
metadata-url - the url to the DigitalNZ API method that will return the full metadata for the record
source-url - the url that will redirect users to the display_url. By using this link (as opposed to the display_url) we are able to count clickthroughs which is helpful for demonstrating the value of DigitalNZ
syndication_date - the date the record was added to DigitalNZ
thumbnail-url - the url of for a thumbnail image of the content to which the record refers. This field may be empty.
title - the title of the record

  • facets - the facet result data (if requested). The facets element will contain one facet-field element corresponding to each facet requested. Each facet-field element contains a sorted list of value elements that are made up of a name and num-results element. See the note below for more information on facets.

 

 

A note on result elements: Some result elements with compound use underscores (like "display_url") to separate words while some use hyphens (like "metadata-url"). To make matters worse the JSON and XML results may use different conventions. We will make this more consistent in a future version of the API.

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 provide the list of values to "Filter by" on the right hand side of the result screen, and the list of categories on the left hand side of the result screen.

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

Examples

Search for 'social welfare' and return only ten results starting at 30:

http://api.digitalnz.org/records/v1.xml/?
search_text=social+welfare&num_results=10&
start=30&api_key=your_api_key

Search for 'social welfare' and sort by ascending content_provider:

http://api.digitalnz.org/records/v1.xml/?
search_text=social+welfare&sort=content_provider&
direction=asc&api_key=your_api_key