Documentation

Endpoints

The API is structured into several endpoints that provide specific functionalities:

/author search all authors /author/{id} content by this author
/client observe API usage
/content search for content /content/{id} get content by ID
/department search all departments /department/{id} content from this department
/keyword search all keywords /keyword/{id} content about this keyword
/product search all products /product/{id} content from this product
/series search all series /series/{id} content in this series

Search Syntax

The q parameter supports simple Solr query syntax for the /content endpoint and all /{ep}/{id} endpoints. Here are a few basics to get you started. For more details check out the Apache Solr documentation.

Full text search: You can search the entire article text and all meta data simply by setting the query parameter to your search phrase. John+Fitzgerald+Kennedy will search for multiple tokens and "John%20Fitzgerald%20Kennedy" will search for the entire string.

Field queries: All fields of an article can be queried individually. For example, to get articles that have the word "Kennedy" in their headline, you would search for title:"Kennedy".

Boolean operators: To form a boolean expression of multiple queries, connect them with
an AND or an OR. So if you want to search the subtitle for "Kennedy" as well, you can modify the query to
title:"Kennedy" AND subtitle:"Kennedy".

Range queries: You can specify a date range for your query using full ISO 8601 date syntax.
Getting all Kennedy related articles from the 60s would work like this:
"Kennedy" AND release_date:[1960-01-01T00:00:00Z TO 1969-12-31T23:59:59.999Z].

Non-content search: All other endpoints currently only support simple search phrases with asterisk wildcards. So, a search for Kennedy related keywords goes like this: /keyword?q=*Kennedy


Pagination

Search results are limited to 10 matches by default. You can increase this value with the limit parameter. To iterate over the resultset, repeat your request with the offset parameter set to multiples of the limit.


Partial Selection

By default, the API returns all available fields for your request. To speed things up, you can specify which fields the server should return using the fields paramter. If the request returns an array of matches, this setting only affects entries within that array. So, for example the field found cannot be deselected, as it always resides outside of the matches array.


Sorting

Search results, namely those of the /content endpoint, can be sorted using the sort parameter. Any of the returned fields are sortable. Direction keywords are asc and desc for an ascending or descending sort order respectively. Multiple sort orders are accepted as a comma-separated list, for example: sort=release_date asc, uuid desc.


Facetting

The content endpoint also provides a faceting interface. You can display facets for specific fields and for date ranges. The facet_field parameter is used to get a frequency distribution for the different values of a field. The facet_date parameter returns counts for the distribution over a specified date range. The facetting results are limited by your search query, but not by pagination parameters.


Parameter Possible values
facet_field keyword, author, series, department, product or any combination
facet_date 1day, 7day, 1month, 1year, 10year or any numerical variation