Custom search records API

Availability: From version 1
History:
Version 2: Changes to accepted parameters so that the call is identical to the search records API.
Method: GET

The custom search records API call is passed a search field and the name of a DigitalNZ custom search and returns results from within that custom search. The custom search records API and this documentation are still under development. Please pass any feedback to the developer forum.

This call is very similar to the search records call, the difference being it only returns results from within a predefined custom search. The power of this is that you can build up complex queries using the visual search builder tool, and then access the data via the API.

URL Format

http://api.digitalnz.org/custom_searches/[version]/[custom_search_title].[format]?[request_parameters]

Request Parameters

The following must be specified as query 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/custom_searches/v1/cominghome.xml?search_text=war&api_key=[Your_API_key]

will search for "war" over the Coming Home custom search.

The following may be specified as request parameters:

  • version_id - a particular version of a custom search. If not specified, the latest version will be used.
  • jsonp - the name of a javascript function that will handle the results if the user requests json format.
  • num_results - the number of results the user wishes returned
  • 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 can not be multi-valued. The sort_field must be one of: category, content_provider, date, syndication_date.
  • 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

Version 2+ accepts the following extra parameters:

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

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/custom_searches/v2/coming_home.xml?search_text=war&api_key=[Your_API_key] e.g. http://api.digitalnz.org/custom_searches/v2/coming_home.json?search_text=war&api_key=[Your_API_key]

Response elements

The search results will return the same elements as the search records API If the jsonp parameter is supplied in the request, the response will be returned in the format jsonp_function_name(json_string)