Search Records API v3


Method: GET
Availability: Available since version 1
History: Query parameters and response formats significantly changed in version 3. V1 & V2 Search Records has been deprecated.


The Search Records API call returns a result set in response to a search query. The v3 Search Records API request parameters and response format differs significantly from the deprecated v1 & v2 Search Records API call.

URL format

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

Request parameters

The following must be specified as request parameters:

  • 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
http://api.digitalnz.org/v3/records.json?api_key=[your_api_key]&text=cat+dog

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][]=Image&or[category][]=Videos"
  • without - Restricts search to records that don't match any of the facet values. Example:
    "&without[category][]=Newspapers"
  • page - the page when iterating over a set of records. (Defaults to 1.)
  • per_page - the number of records the user wishes returned up to a maximum of 100. (Defaults to 20.)
  • 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_page - the facet page to iterate over a set of facets. . (Defaults to 1.)
  • facet_per_page - the number of facets returned for every page. (Defaults to 10.)
  • sort - the field upon which results are sorted. Defaults to relevance sorting. The sort field must be either "date" or "syndication_date".
  • direction - the direction in which the results are sorted. Possible values: "desc", "asc".
  • geo_bbox - a geographic bounding box scoping a search to a geographic region. Order of latitude-longitude coordinates is north, west, south, east. For example, &geo_bbox=-41,174,-42,175 searches the Wellington region.

    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, rss.

    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:

    • 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:
      • is_commercial_use - this record is licensed for commercial use
      • category - a string containing one or more category names separated by a comma (e.g. Images, Web pages)
      • content_partner - 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
      • additional_description - additional text describing the record
      • landing_url - the url for the content on the contentpartner's website. Please use the source_url when providing HTML links (see below)
      • id - the internal DigitalNZ identifier (used by the Get Metadata API)
      • source_url - the url that will redirect users to the landing_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
      • geo_co_ords - The latitude and longitude in the following format: namespace:lat,long;
        Multiple values are seperated by semi-colons, for example: namespace:lat,long;namespace:lat,long;namespace:lat,long;
        NOTE: namespace is optional.
      • 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 - the copyright statement applying to the object. This field may be empty.
      • license - the licence for the object. This field may be empty.
      • rights_url - the url of the object licence. This field may be empty.
      • display_date - string with date information in multiple, often unstructured formats (e.g. Circa 2000)
      • peer_reviewed - boolean, associated with research paper items. True indicates the research paper has been peer reviewed
      • marsden_code - a number indicating the field of research
      • author - lists the author's names
      • no_landing_page - boolean value, if set to true it indicates the item doesn't have an external landing page, usually because it is a downloadable item such as a pdf or mpeg
      • object_url - a url pointing to a downloadable object, i.e. an image, pdf or mpeg
      • published_date - list of dates published 
      • publisher - lists the publisher's names
      • dctype - Dublin Core categorisation indicating type
      • library_collection - the library collection the item belongs to
      • display_collection - the display collection the item belongs to
      • collection_parent - the item's parent collection
      • collection_root - the top level collection
    • 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 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, 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