Search Facade

Overview

Whilst content browsing is still the most common way to discover content, search is a very useful tool when trying to find specific content by one of its features, such as title, actor or description. A benefit of this functionality is that other content can also be discovered. 

OpenTV Video Platform facilitates content search either via the Search Façade (where multiple content sources can be searched simultaneously) or via direct MDS search. It is recommended that Search Façade be used as the default configuration, as this encapsulates the underlying MDS search, and it also ensures that additional search engine use can be catered for should this be required in the future.

The Search Façade has a generic interface, removing the need for knowledge of bespoke search engine query calls. Exposing the search functionality in this way allows for a greater degree of control over the queries that can be performed, which in turn then allows for better performance tuning and more predictable scaling.

Each supported search solution is facilitated by its own Search Façade adapter. The addition of future search solutions will depend on the deployment of similar adapters.

Request

To make a search request, send a GET request to:

http://<hostname>/search/v1/search?q=<search_term>&<other_query_params>

Headers

• authorization – bearer token that the client received at signon

• nv-tenant-id – the tenant ID

Mandatory arguments

• search_term– the term to be searched for

Other arguments

• type – the type of results to return. One of:

  • vod

  • stcu

  • ltcu

  • series

  • season

  • channel

  • programme

• category – filter by the specified category, genre, or sub-genre

• group – roll up multiple results into the containing type. One of:

  • series – roll up into series

  • season – roll up into season

  • year – roll up into year

  • content – roll up results from different sources (e.g., multiple repeats of the same episode, LTCU, and a deep-link to an external platform) into a single result. This single search result will have a grouped element containing the related items.

• provider – limit the results to the specified provider (for deep-link support)

• engine – limit the results to the specified search engine(s). If you specify multiple search engines, you can specify a limit for each one (except the last). The limit determines the number of results from the search engine that it applies to. The last engine does not require a limit as all the remaining results will be from this one.
  For example, ?engine=SOLR:10&engine=CUSTOM.

• excludeProvider – excludes the specified provider(s) from the results. This is related to deeplink support.

• onlyplayable – if specified and set to true, limits results to content that can be played now.

• locale – the locale for the search

• device – the type of device running the search. Specifying device ensures that Search Façade will only return results for which the content can be played on the device.

• Rating-related parameters:

  • rating – filter the results to match the specified rating code(s)
    Note: the age rating used to filter the results will be the lower of that specified here and the maxAgeRating of the current user profile.

  • ratingSystem – the rating system to use (e.g., BBFC). If you do not specify the rating system, Search Façade will look for the first matching rating in its configuration.

  • ratingPrecedence – the same as rating, but using the raw precedence information

• Paging parameters:

  • limit – the number of records to return

  • page – the page number to return (cannot be used without limit)
    For example:

    • ?limit=10 returns the first 10 records.

    • ?limit=10&page=2 returns the second 10 records.

  • offset – the number of records to skip

If multiple provider data sources are configured, the searches execute concurrently across each provider.

Response

Irrespective of the different underlying search engine data sources, Search Façade ensures the delivery of the response in a uniform generic data structure.

The API supports the following in the response:

• A combined row of results

  • If search results grouping is "Combined", or overridden in search query

• A row of results per provider

  • If search results grouping is "Split", or overridden in search query

• A generic data structure that provides the client with enough information to display the results and/or request further information for enrichment

  • Data structure is consistent between the NAGRAVISION internal search facility and any external search provision

Search Façade can return many types of results:

• Generic

• Channel

• Programme

• Series

• Season

• STCU

• LTCU

• VoD

In the case of BTV (live), content can migrate through a number of phases: Programme → STCU → LTCU

In some cases, these phases may overlap (e.g., LTCU and STCU validity overlap). In cases like this, where both content types are available and valid, and a return type is not specified in the request, Search Façade will only return the LTCU content (instead of returning multiple results for the same content).

A successful request returns an HTTP 200 status.

Example

A successful request with a search query of ?q=star&limit=2 will return a response that looks like this:

{
    "NAGRA": [
        {
            "id": "GLOBAL_ND0000003436_Series",
            "title": "Starman",
            "type": "series",
            "locale": "en_GB",
            "source": "NAGRA",
            "description": "serie"
        },
        {
            "id": "GLOBAL_ND0000003435_Series",
            "title": "Starman",
            "type": "series",
            "locale": "en_GB",
            "source": "NAGRA",
            "description": "serie"
        }
    ]
}

See also

Search Facade API documentation