Search Publications
Required scope:
public-api:read
Description
This endpoint allows filtering for published documents.
Use Cases
- Automatic teaser lists like topic pages (filtered by Metadata properties)
- Ticker Tool
Notes
- Even when it’s possible to make a full-text search to this endpoint, it’s not thought to be used by a frontend search (because of performance reasons)
Endpoint
GET api/v1/publications/search
Parameters
| Name | Type | Notes |
|---|---|---|
| ?search | string | Search term to perform a full-text search with. For exact word matches use “, e.g. ‘search=“Ukulele”’ |
| ?contentTypes | string | Comma separated list of content-types for which documents should be found. Content types are concatenated with OR. Example: ‘regular,author’ |
| ?categories | string | Comma separated list of category ids for which documents should be found. Categories are concatenated with OR. Example: ‘sport,fashion’ |
| ?languages | string | Comma separated list of languages for which documents should be found. Languages are concatenated with OR. Example: ’en,de' |
| ?languageGroupId | string | A GroupId used to fetch all translations of a document Using the ?languages param a document in a specific language can be fetched. Example: ‘?languageGroupId=47?language=de’ |
| ?filters | string | A JSON string which follows the search filters query DSL. |
| ?sort | string | Comma separated list of sort properties. Any of the Sort Fields can be used. The sort order can be reversed by prefixing the property with a ‘-’. |
| ?fields | string | Comma separated list of properties to include in the response. Defaults to ‘systemdata,metadata,content’ (no renditions). Use ‘id’ if you only want to retrieve the ids of the published documents. Useful (and faster) if you are fully synchronizing your frontend with the publication events. |
| ?limit | integer | A limit for how much published documents to retrieve. Defaults to 10. Max. 100. |
| ?offset | integer | An offset into the query. Useful when getting more than 100 results (pagination). Max. 10000. |
| ?ignoreComponentConditions | boolean | Provides a way to opt out of component filtering and return all content regardless of whether each component passes the conditional checks. Added in: release-2024-03Default: false |
| ?componentConditions | string | JSON stringified object which contains the component conditions you would like to apply. Added in: release-2024-03Default: dateTime: new Date()Example: ?componentConditions={"dateTime":"2024-02-14T17:25:10.391Z"} |
Response
Search Filters
Added in: release-2023-07
Search filters can be used to filter documents using a custom query DSL.
Filter Fields
| Property | Type |
|---|---|
| documentId | long |
| contentType | keyword |
| firstPublicationDate | date |
| lastPublicationDate | date |
| significantPublicationDate | date |
| visiblePublicationDate | date |
| statistics.characterCount | integer |
| statistics.componentCount.* | integer |
| metadata.* | Any |
Metadata fields must be indexed. Please read the Publication Index guide for further information. Details of the core metadata plugins, along with their built-in indexing capabilities, can be found in the Metadata Plugin List.
The index type of each field will determine which query capabilities are supported:
| Type | Term | Range | Exists | Sort |
|---|---|---|---|---|
| keyword | ✔ | ✔ | ✔ | ✔ |
| integer | ✔ | ✔ | ✔ | ✔ |
| float | ✔ | ✔ | ✔ | ✔ |
| double | ✔ | ✔ | ✔ | ✔ |
| long | ✔ | ✔ | ✔ | ✔ |
| date | ✔ | ✔ | ✔ | ✔ |
| boolean | ✔ | ✗ | ✔ | ✗ |
Query Expressions
Term
The standard value comparison behaviour.
An exact match is required, although some type coercion may be applied.
{
key: 'metadata.title',
term: 'My Title'
}
An array can also be provided as the ’term’ value, which behaves like an OR operator.
{
key: 'metadata.language.locale',
term: ['de', 'fr']
}
Range
Search within a range.
{
key: 'metadata.count',
range: {lte: 2}
}
Multiple range terms (‘gt’, ‘gte’, ’lt’, ’lte’) can be combined.
{
key: 'metadata.count',
range: {gt: 1, lt: 5}
}
Exists
Check if a property has been set.
When querying a metadata property with an object value, always use the key of a leaf node (e.g. metadata.teaserImage.mediaId), because the parent itself (e.g. metadata.teaserImage) is not indexed.
{
key: 'metadata.teaserImage.mediaId',
exists: true
}
Logical Operators
The logical operators allow you to group queries, and to change from the default AND behaviour of the top-level array. All logical operator values can be an object, or an array, containing logical operators or query expressions.
AND
All conditions must be met for a publication to be included in the results.
{
and: [
{key: 'metadata.news', term: true},
{key: 'metadata.teaserImage.mediaId', exists: false}
]
}
OR
Any condition can be met for a publication to be included in the results.
{
or: [
{key: 'metadata.image.mediaId', exists: true},
{key: 'metadata.teaserImage.mediaId', exists: true}
]
}
NOT
This operator negates the expression contained within.
{
not: {key: 'metadata.language.locale', term: 'de'}
}
To negate multiple conditions nest another logical operator within.
{
not: {
or: [
{key: 'metadata.news', term: false},
{key: 'metadata.language.locale', term: 'fr'}
]
}
}
Example
An example of how the logical operators and query expressions can be combined to create a more complex query:
const filters = JSON.stringify({
or: [
{
and: [
{
key: 'metadata.count',
range: {lte: 2}
},
{
key: 'metadata.bool',
exists: true
},
{
not: {
key: 'metadata.title',
term: 'My Title'
}
}
]
},
{
key: 'metadata.count',
term: 3
}
]
})
const response = await fetch(`api/v1/publications/search?filters=${filters}`)
const results = await response.json()
Sort Fields
Valid sort fields are:
relevancesortDatedocumentIdcontentTypefirstPublicationDatelastPublicationDatesignificantPublicationDatevisiblePublicationDatemetadata.*
The default sort order is sortDate descending (see Sort Date), with documentId descending used as a fallback when multiple results have exactly the same sortDate.
relevance will only have an affect if you provide a search term.
Most metadata properties can be used to sort, but not those indexed as text or boolean (see Filter Fields).
When a string is used to define the sort order, the order can be reversed by prefixing the property with a - (e.g. -sortDate,documentId).
Documents which don’t have an indexed value will appear at the end of the results.
