Custom search records API

The custom search records API call is passed a search query and the name of a DigitalNZ custom search and returns results from within that custom search.

Status: Beta! 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 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

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/v1/coming_home.xml?
search_text=war&api_key=[Your_API_key]

e.g. http://api.digitalnz.org/custom_searches/v1/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