/api/search.json performs the same search as the search screen (see Zoeken) and returns the result in a single response rather than whilst the search is still in progress. The address can be queried without an account and without a key.
Parameters
q: the search term. Mandatory; if it is missing, the address returns a 400 status code;modeis one of four values. If it is missing, then ‘all’ applies:all: every word appears in the same text (the standard);any: at least one of the words appears;near: each word is within ten words of the other;exact: the words are written together and in exactly this order.
For further details on what the four mean and how a source without its own ‘or’ or ‘proximity’ is handled, see Zoeken;
page_size:100,500,1000ormax(the source’s own maximum). If this is missing, the default set for this installation applies:100, unless the administrator has changedBesluitBron:Search:PageSize;date_from,date_to: the boundaries of the date filter, in the formjjjj-mm-dd. An empty boundary leaves that side open;date_undated:1to display results without a date whilst the date filter is active, i.e. whilstdate_fromordate_tois set. Without either of these limits, this parameter has no effect: in that case, the filter is not active anyway and every result is included, with or without a date. The functionality is described at Zoeken, under ‘Filtering by date’;culture: the language of the result, the comment and the method, as specified by the source; for example,de. If this is missing, the language is determined by the requester’s language cookie; otherwise,Accept-Language.
An invalid value is an error, not a silent fallback
Since version 1.3.86, the server returns a 400 status code whenever mode, page_size, date_from or date_to contains a value not listed above, with a ‘error’ field indicating which parameter was affected and a ‘error_description’ listing the permitted values. For example, mode=xxx and page_size=250 both return a clear error message rather than silently falling back to the default value. This differs from the search screen itself: there, an invalid value in the address bar reverts to the default, because a visitor rarely reads a typed address bar accurately and an error message there solves nothing. A programme that calls this address can, however, correct its own error, so it is shown the error rather than a silently corrected assumption of what it intended.
What the address returns
A single response containing the search term, the individual words, the method used, the duration and, for each source, the result, the number of hits, the total figure provided by the source itself, and whether that total is a count or an estimate. The sources are listed alphabetically, not in the order in which they responded: this site returns the search results as soon as they are ready, so there is no order of receipt to maintain.
Each source provides no more than the number requested by page_size, which is the same limit applied by the site itself. If page_size requests more than the number of items the source can provide in a single query, this address will itself fetch multiple pages from that source until the requested number is reached or the source has no more items to provide, from version 1.3.86 onwards.
A source may have its own strict limit that page_size cannot exceed: OpenTK, for example, never returns more than two hundred and eighty results for a single search query. If this is the case, the response for that source will state ‘at_absolute_ceiling: true’ (from version 1.3.86 onwards): no higher ‘page_size’ and no further queries will retrieve any additional results from it.
The shared budget
This endpoint shares the budget for one search per second with the search screen, as both query the same source platforms. Once that budget is exhausted, the endpoint returns a 429 status code and a ‘Retry-After’ field indicating how many seconds to wait.
What is recorded
A request to this address is logged in the same way as a search on the screen: one line per source in the request log, under the category ‘SEARCH’. See Privacy en Cookies.