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.

For more comprehensive details about the API parameters and responses see the DigitalNZ OpenAPI spec on SwaggerHub.

URL format

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

Request parameters, optional

The following may be specified as request parameters:

  • and - Restricts search to records matching all facet values. Example:

    …&
    and
    [content_partner][]=Kete+Horowhenua&
    and
    [category][]=Images

  • or - Restricts search to records matching any of the specified facet values. Example:

    …&
    or
    [category][]=Images&
    or
    [category][]=Videos

  • without - Restricts search to records that don't match any of the facet values. Example:

    …&
    without
    [category][]=Newspapers

  • per_page - The number of records to return per page of search results. Maximum of 100. Defaults to 20.

  • page - Which page of results to return. Defaults to 1.

  • facets - A list of facet fields to include in the output. See the note on facets below for more information. Example:

    …&
    facets
    =year,category

  • facets_per_page - The number of facets to return per page of facets fields. Defaults to 10.

  • facets_page - Which page of facet fields to return. Defaults to 1.

  • sort - The field upon which results are sorted. Defaults to relevance sorting. The sort field must be either 

    date
    or 
    syndication_date
    .

  • direction - The order in which the results are sorted. Possible values: asc (ascending) or desc (descending).

  • geo_bbox - A geographic bounding box scoping a search to a geographic region. Order of latitude-longitude coordinates is north, west, south, east. The following example searches the Wellington region:

    …
    &geo_bbox=-41,174,-42,175

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
?text=cat+dog

http://api.digitalnz.org/v3/records.
json
?text=cat+dog

http://api.digitalnz.org/v3/records.
rss
?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:

  • result_count - total number of matching search results.

  • results - search result records

  • The results elements will contain 0 or more result elements, each representing a single record. Each record element will contain a varying combination of metadata fields such as:

    • is_commercial_use - whether or not this record is licensed for commercial use

    • category - comma-separated list of categories applied to this record (e.g. Images, Web pages)

    • content_partner - institution holding the content to which this record refers

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

    • description - text describing this record

    • additional_description - additional text describing this record

    • landing_url - URL for the content on the content partner's website.
      NB: Please use the source_url (see below) when providing HTML links.

    • id - internal DigitalNZ identifier (used by the Get Metadata API call)

    • source_url - URL that will redirect users to the landing_url.
      NB: Please provide this URL (as opposed to the landing_url) in public hyperlinks so that we are able to count click-throughs, which is helpful for demonstrating the value of DigitalNZ, thus helping us to continue our service.

    • syndication_date - date this record was added to DigitalNZ

    • thumbnail_url - URL for a thumbnail image of the content to which this record refers. This field may be empty.

    • title - title of this record

    • large_thumbnail_url - a larger thumbnail image with dimensions up to 800px (NB the API Terms do not extend rights to the use of these thumbnails)

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

    • rights_url - URL of the object licence. This field may be empty

    • display_date - date information in various, often unstructured, formats (e.g. Circa 2000)

    • dc_type - Dublin Core categorisation indicating type

    • display_collection - the display collection the item belongs to

  • 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 result count element. See the note below for more information on facets.

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?
text
=Auckland
&and[is_commercial_use]
=True

For the latest list of DigitalNZ Partners that allow their metadata for use in commercial applications, use this query:

https://api.digitalnz.org/records.json?
&and[is_commercial_use]
=true&
facets
=content_partner&per_page=1&
fields
=is_commercial_use&facets_per_page=350

Examples

Search for 'social welfare' and return only ten results per page, starting at page three:

http://api.digitalnz.org/v3/records.json?
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?
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?
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?
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?&
geo_bbox
=-41,174,-42,175&
text
=kiwi