Searching with Search Facade

Request

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

https://<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.
  Note: you can get a list of available search engines using GET http://<hostname>/search/v1/engines. See the Search Facade API documentation.
  The default search engine is configured at the platform level – see Managing search.

• 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.

• history – whether to include this search query in the user profile’s search history (true or false). See Getting the search history.

• 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 Facade 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 Facade 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 Facade 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 Facade 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

• Managing search

• Searching using search rails

• Search Facade API documentation