Search

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)
Curl Example
ACCESS_TOKEN=ey1234
curl -k -X GET "https://server.livingdocs.io/api/v1/publications/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint

GET api/v1/publications/search

Parameters

NameTypeNotes
?searchstringSearch term to perform a full-text search with. For exact word matches use “, e.g. ‘search=“Ukulele”’
?contentTypesstringComma separated list of content-types for which documents should be found. Content types are concatenated with OR. Example: ‘regular,author’
?categoriesstringComma separated list of category ids for which documents should be found. Categories are concatenated with OR. Example: ‘sport,fashion’
?languagesstringComma separated list of languages for which documents should be found. Languages are concatenated with OR. Example: ’en,de'
?languageGroupIdstringA 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’
?filtersstringA JSON string which follows the search filters query DSL.
?sortstringComma 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 ‘-’.
?fieldsstringComma 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.
?limitintegerA limit for how much published documents to retrieve. Defaults to 10. Max. 100.
?offsetintegerAn offset into the query. Useful when getting more than 100 results (pagination)

Response

200
OK
api/v1/publications/search?search=Obama
[
  {
    "systemdata": {
      "projectId": 1,
      "channelId": 1,
      "documentId": 1,
      "contentType": "article",
      "documentType": "article",
      "layout": "regular",
      "design": {
        "name": "timeline",
        "version": "1.1.0"
      }
    },
    "metadata": {
      "title": "Obama re-elected",
      "description": "some lead",
      "dependencies": {},
      "testDependency": "li-test-dependency.onUpdate is correct"
    },
    "content": [
      {
        "id": "doc-1b8i1ksh10",
        "component": "head",
        "identifier": "timeline.head",
        "content": {
          "title": "Obama re-elected",
          "text": "some lead"
        }
      },
      {
        "id": "doc-1b8i1ksh20",
        "component": "normal",
        "identifier": "timeline.normal",
        "content": {
          "caption": "my caption"
        },
        "styles": {
          "position": "left"
        }
      },
      {
        "id": "doc-1b8i1ksh30",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "first paragraph"
        }
      },
      {
        "id": "doc-1b8i1me1d0",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "second paragraph"
        }
      }
    ]
  }
]
200
OK
api/v1/publications/search?categories=sport,fashion&languages=en
[
  {
    "systemdata": {
      "projectId": 1,
      "channelId": 1,
      "documentId": 1,
      "contentType": "article",
      "documentType": "article",
      "layout": "regular",
      "design": {
        "name": "timeline",
        "version": "1.1.0"
      }
    },
    "metadata": {
      "title": "Bayern to win Champions League",
      "description": "some lead",
      "category": {
        "id": "sport"
      },
      "language": {
        "locale": "en"
      },
      "dependencies": {},
      "testDependency": "li-test-dependency.onUpdate is correct"
    },
    "content": [
      {
        "id": "doc-1b8i1ksh10",
        "component": "head",
        "identifier": "timeline.head",
        "content": {
          "title": "Bayern to win Champions League",
          "text": "some lead"
        }
      },
      {
        "id": "doc-1b8i1ksh20",
        "component": "normal",
        "identifier": "timeline.normal",
        "content": {
          "caption": "my caption"
        },
        "styles": {
          "position": "left"
        }
      },
      {
        "id": "doc-1b8i1ksh30",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "first paragraph"
        }
      },
      {
        "id": "doc-1b8i1me1d0",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "second paragraph"
        }
      }
    ]
  }
]
200
OK
api/v1/publications/search?contentTypes=regular,gallery&limit=10&offset=10
[
  {
    "systemdata": {
      "projectId": 1,
      "channelId": 1,
      "documentId": 1,
      "contentType": "regular",
      "documentType": "article",
      "layout": "regular",
      "design": {
        "name": "timeline",
        "version": "1.1.0"
      }
    },
    "metadata": {
      "title": "Bayern to win Champions League",
      "description": "some lead",
      "category": {
        "id": "sport"
      },
      "language": {
        "locale": "en"
      },
      "dependencies": {},
      "testDependency": "li-test-dependency.onUpdate is correct"
    },
    "content": [
      {
        "id": "doc-1b8i1ksh10",
        "component": "head",
        "identifier": "timeline.head",
        "content": {
          "title": "Bayern to win Champions League",
          "text": "some lead"
        }
      },
      {
        "id": "doc-1b8i1ksh20",
        "component": "normal",
        "identifier": "timeline.normal",
        "content": {
          "caption": "my caption"
        },
        "styles": {
          "position": "left"
        }
      },
      {
        "id": "doc-1b8i1ksh30",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "first paragraph"
        }
      },
      {
        "id": "doc-1b8i1me1d0",
        "component": "p",
        "identifier": "timeline.p",
        "content": {
          "text": "second paragraph"
        }
      }
    ]
  }
]
200
OK
api/v1/publications/search?contentTypes=article&limit=999&fields=id
[
  {
    "documentId": 1,
    "projectId": 1
  },
  {
    "documentId": 2,
    "projectId": 1
  }
]

Search Filters

Added in: release-2023-07

Search filters can be used to filter documents using a custom query DSL.

Filter Fields

PropertyType
documentIdlong
contentTypekeyword
firstPublicationDatedate
lastPublicationDatedate
significantPublicationDatedate
visiblePublicationDatedate
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:

TypeTermRangeExistsSort
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:

  • relevance
  • sortDate
  • documentId
  • contentType
  • firstPublicationDate
  • lastPublicationDate
  • significantPublicationDate
  • visiblePublicationDate
  • metadata.*

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.