Keyword suggestion

Overview

Users will expect the UI search functionality to provide suggestions for keywords as they start entering text before selecting a keyword to search for or just using the entered one. This reduces the time taken to enter the keyword as they only need to enter part of the keyword before the UI suggest the required one.

MDS builds an index of keywords based on the content metadata. By default, the fields indexed for the suggest API are actor and content title, and the ranking of each keyword is based on the occurrence of the keywords in the content metadata, and the relative importance of the field it is within.  For example, if an actor such as Tom Cruise is in more movies or TV shows than Tom Hanks, then when "Tom" is entered, Tom Cruise will be returned with a higher rank. Other fields can be configured to boost the ranking of a keyword if the keyword is found there, however, this type of customisation is project-specific.

The suggest API matches on the beginning of words only, it will not match on the middle or end of words as this would require the searchable index to be too large, and confusing to use in practice.

Basic suggest query for a single string with no filter

The following example searches for matches with 'Joh' in them:

http://<host>:<port>/search/v1/suggest?q=Joh

If the appropriate metadata exists, the expected results might be:

• Johnny Depp - Actor

• John Cusack - Actor

• Being John Malkovich - Title

• John Carter - Title

• John Lithgow - Actor

• John Hurt - Actor

• Dear John - Title

• John Travolta - Actor

• John  Barrowman - Actor

• John Tucker Must Die - Title

Suggest query for a single string for titles only

In the following example, a filter is used to restrict the previous query to content titles only:

http://<host>:<port>/search/v1/suggest?q=Joh&fq=entity:content

Based on the example above, the expected results might be:

• Being John Malkovich - Title

• John Carter - Title

• Dear John - Title

• John Tucker Must Die - Title

Suggest query using two strings

You can use multiple strings in the query, separated by a space. Again, these must be the beginning of words or full words.

http://<host>:<port>/search/v1/suggest?q=Joh C

Given the first use case, the expected results might now only be:

• John Cusack - Actor

• John Carter - Title

Filtering a suggest query by scope and domain

You can filter a suggest query by scope and domain. Scope means either live TV data (btv) or on-demand data (vod), while domain means the device and region combination used.

To retrieve keyword suggestions for Joh in on-demand for an iPad located in Sao Paulo:

http://<host>:<port>/search/v1/suggest?q=Joh C&fq=scope:vod&fq=domain:("ipad|Sao Paulo")

To retrieve keyword suggestions for Joh in live TV for any device in France:

http://<host>:<port>/search/v1/suggest?q=Joh C&fq=scope:btv&fq=domain:("|France")

Restricting a suggest query to certain nodes

The UI might want to restrict the suggest query to a specific on-demand node and its child nodes. This is especially useful in deployments where the on-demand catalogue is split into distinct areas such as movies, TV shows, box sets, catchup TV, and so on. To use this feature, you must specify the node representing the root of the tree to which the results are restricted.

For example, to restrict the results to only the contents of the movies node (and all its sub-nodes), where the movies node ID is Movies_12345, use the following query:

http://<host>:<port>/search/v1/suggest?q=Joh C&fq=scope:vod&fq=domain:("STB|UK")&descendantsOf:Movies_12345

See also​

Search Facade API documentation