Search API

Query

The following parameters decide the results that are retrieved from the search index

terms

Terms to search for.

Example

  1. GET /rep/search?terms=i+love+you&display_fields=f_transcript

Response

{
  "pagination": {
    ...
  },
  "results": [
    {
      "fields": {
        "f_transcript": [
          "i love you"
        ]
      },
      "hash": "hq__BADSKjreLtmjgW4LTvaTVPejQtEyiHZPb5Eeueopne4Nr58bcjowxnFospfBN6Gv8rUYGyM5x5",
      "id": "iq__rEsFEuNEXDkNfHqycdaWrv4r2LZ",
      ...
    }
  ],
  ...
}

semantic (bool)

This option helps to search the query within the appropriate fields and also prioritizes exact matches (Highly Recommended).

Furthermore, the query will be preprocessed leniently… meaning non-alphanumeric characters will be removed.

Example

GET /rep/search?terms=i+love+you&semantic=true

  1. Users cannot use advanced syntax in terms if semantic=true
  2. For advanced queries, use the filters argument (see below) in combination with terms.

filters

Additional filters. Users can embed advanced syntax here to narrow the result set.

Examples

GET /rep/search?terms=i+love+you&semantic=true&filters=f_release_date:[1965-09-17 TO 1975-09-17}

This example will narrow the resulting documents to those which have a release date field in the specified range.

search_fields

Specifies which fields will be searched. Default: defaults to all searchable fields.

Example

GET /rep/search?terms=12+angry+men&search_fields=f_display_title

This example will search for 12 Angry Men only looking at the display title field and ignoring potential matches in other fields.

rank_fields (bool)

If set to true, this will exponentially boost matches in fields which are provided earlier in search_fields.

Example

GET /rep/search?terms=12+angry+men&search_fields=f_display_title,f_synopsis,f_actor&rank_fields

This query will search “12 Angry Men” in the display title, synopsis, and actor fields. However it will weight matches in the display title twice as high as matches in the synopsis which are similarly weighted twice as high as matches in the actor field, and so on.

  1. search_fields must be nonempty if rank_fields is set to true (Default: false).

unscored

Ignore scoring of results. Setting this to false can lead to slightly faster performance for use cases where ordering of the results is not important.

Default: false

Results

Parameters affecting what the api returns based on the search result

display_fields

Specify fields to display in the results.

If you wish to display all indexed fields, set display_fields=all.

Example:

GET /rep/search?terms=i+love+you&display_fields=f_transcript

Default: empty

Response

{
  "pagination": {
    ...
  },
  "results": [
    {
      "fields": { 
        "f_transcript": [
          "i love you" (display_fields adds this)
        ]
      },
      "hash": "hq__BADSKjreLtmjgW4LTvaTVPejQtEyiHZPb5Eeueopne4Nr58bcjowxnFospfBN6Gv8rUYGyM5x5",
      "id": "iq__rEsFEuNEXDkNfHqycdaWrv4r2LZ",
      ...
    }
  ],
  ...
}

sort

Sorts by a given comma separated list of fields. The direction of the sort can be specified by adding @asc or @desc to the end of the field name (defaults to ascending order).

Example

sort=display_title@asc,f_release_date@desc,

Sort first by display_title and if there are two equivalent titles put the more recent titles first.

Important:

  1. sort will override the default scored order, so it is only recommended if scoring is not important
  2. Results which do not have the field in question present will be discarded from the results

get_snippets (bool)

Get back the matched text for each result in an html “snippet”. Matched terms are bolded. (Default: false)

Example

GET /rep/search?terms=i+love+you&get_snippets&display_fields=f_transcript

The parsed html would read: *it’s okay i love you so much i love you

{
  "pagination": {
    ...
  },
  "results": [
    {
      "fields": {
        "f_speech_to_text": [
          "it's okay i love you so much i love you"
        ]
      },
      ...,
      "snippets": { <- (get_snippets adds this)
        "f_display_title": "",
        "f_speech_to_text": "it&#x27;s okay <b>i</b> <b>love</b> <b>you</b> so much <b>i</b> <b>love</b> <b>you</b>",
        ...
      },
      "type": "hq__LRXgHD7Dxe7vub584qVzZPDBbK6ZiWZhEZKJHsHLbT1DpzdUqwDeYnqr1QXKmuLMaoHQVkJTvQ"
    }
  ],
  ...
}

stats

A list of fields which we want to compute search result stats on. The stats are generated based on the returned documents before any pagination occurs (see Pagination section below). For instance, we can get just the result statistics by setting limit=0

Example

GET /rep/search?terms=i+love+you&display_fields=f_transcript&stats=f_actor&limit=0

Here we see no results because limit=0 however we see a full list of actor occurrences in the top 128 matches to the query “i love you”

Response

{
  "pagination": {
    "limit": 0,
    "max_total": 128,
    "start": 0,
    "total": 128 <- (total number of results that stats are computed on)
  },
  "results": [], <- (no results displayed, because limit=0)
  "stats": {
    "f_actor": {
      "max": "Aubrey Plaza",
      "min": "Alex Winters",
      "total": 34,
      "unique": 26,
      "histogram": {
        "Aubrey Plaza": 1,
        "Audrey Hepburn": 2,
        ... (many others)
        "Sylvester Stallone": 4,
        "Talia Shire": 1,
        "Woody Allen": 1
      }
    }
  },
  "warnings": []
}

select and remove

Use these options to include content object metadata in the search results. See documentation on the fabric API for content metadata retrieval for more information.

Example

GET /rep/search?terms=i+love+you&select=/public/asset_metadata/display_title,/public/asset_metadata/info/genre

Result

{
  "pagination": {
    ...
  },
  "results": [
    {
      "fields": {
        "f_speech_to_text": [
          "it's okay i love you so much i love you"
        ]
      },
      ...,
      "meta": { <- (select populates this section)
        "public": {
          "asset_metadata": {
            "display_title": "Hotel Rwanda",
            "info": {
              "genre": [ 
                "Drama",
                "War",
                "Historical"
              ]
            }
          }
        }
      },
      ...
    }
  ],
  "stats": {},
  "warnings": []
}

Pagination

These parameters affect which results are shown to the user after being retrieved. These are useful for breaking the result set into multiple pages in the UI.

max_total

The total number of docs we wish to obtain from our query before paginating with start and limit. (Default: 80)

start

Start specifies the ordered position of the first document we wish to return, after sorting. All documents sorted to an earlier position will be discarded in the result. (Default: 0)

limit

Number of documents to return from the start. (Default: 64)

Pagination Example

GET /rep/search?terms=hello+world&max_total=500&start=100&limit=200&stats=f_title

Retrieve up to 5000 documents from the index. These documents will be sorted and will be used to compute result stats, but before presenting results to the end user the result set is trimmed to return only the 100th document up to the 199th document.

Clip Search

Parameters related to the clip search feature for search on playable content objects. Given that documents are indexed with start_time/end_time fields this gives a way to return playable url’s along with the result set.

clips (bool)

If true, this will return results as clips with start/end time and playable url attached

Example

GET /rep/search?terms=i+love+you&limit=1&clips&display_fields=f_transcript

Result

{
  "pagination": {
    ...
    "total_clips": 1
  },
  "stats": {},
  "contents": [
    {
      ...
      "url": "/q/hq__GeoR1kmiXYyqDMJKMgqpukuN6B3ZqRctmsadBp7oyFWMQpMvBREXtRA4HsCZyZfazXyFhhSD2b/rep/playout/clips/options.json?clip_start=1316.149000&clip_end=1321.071000&ignore_trimming=true",
      "image_url": "/q/hq__GeoR1kmiXYyqDMJKMgqpukuN6B3ZqRctmsadBp7oyFWMQpMvBREXtRA4HsCZyZfazXyFhhSD2b/rep/frame/clips/video?t=1316.149000&ignore_trimming=true",
      "start": "21m56.149s",
      "end": "22m1.071s",
      "start_time": 1316149,
      "end_time": 1321071,
      "source_count": 1,
      "sources": [
        {
          "prefix": "/video_tags/metadata_tags/0002/metadata_tags/shot_tags/tags[35]",
          "fields": {
            "f_end_time": [
              1321071
            ],
            "f_speech_to_text": [
              "it's okay i love you so much i love you"
            ],
            "f_start_time": [
              1316149
            ]
          }
        }
      ]
    }
  ]
}

clips_include_source_tags (bool)

Specify whether to include clip information in the results under the "sources" entry.

This will include any fields requested through display_fields and any metadata requested through select. It will also return the document prefix (where in the content object metadata the document was built from)

By default f_start_time and f_end_time are added to display_fields. (Default: true)

Example

GET /rep/search?terms=i+love+you&limit=1&clips&display_fields=f_transcript&clips_include_source_tags=true

Result

{
  "pagination": {
    ...
    "total_clips": 1
  },
  "stats": {},
  "contents": [
    {
      ...
      "url": "/q/hq__GeoR1kmiXYyqDMJKMgqpukuN6B3ZqRctmsadBp7oyFWMQpMvBREXtRA4HsCZyZfazXyFhhSD2b/rep/playout/clips/options.json?clip_start=1316.149000&clip_end=1321.071000&ignore_trimming=true",
      "image_url": "/q/hq__GeoR1kmiXYyqDMJKMgqpukuN6B3ZqRctmsadBp7oyFWMQpMvBREXtRA4HsCZyZfazXyFhhSD2b/rep/frame/clips/video?t=1316.149000&ignore_trimming=true",
      "start": "21m56.149s",
      "end": "22m1.071s",
      "start_time": 1316149,
      "end_time": 1321071,
      "source_count": 1,
      "sources": [ <- (This section comes from clips_include_source_tags=true)
        {
          "prefix": "/video_tags/metadata_tags/0002/metadata_tags/shot_tags/tags[35]",
          "fields": {
            "f_end_time": [
              1321071
            ],
            "f_speech_to_text": [
              "it's okay i love you so much i love you"
            ],
            "f_start_time": [
              1316149
            ]
          }
        }
      ]
    }
  ]
}

max_duration

Limit the maximum clip duration allowed (in seconds). The clip postprocessing will trim clips that exceed this duration

Example

GET /rep/search?terms=i+love+you&limit=1&clips&display_fields=f_transcript&clips_include_source_tags=true&max_duration=60 Default: 5 minutes

coalescing_span

Adjacent clips with distance apart of less than coalescing_span (in seconds) will be merged into one result.

Example

GET /rep/search?terms=i+love+you&limit=1&clips&display_fields=f_transcript&clips_include_source_tags=true&max_duration=60&coalescing_span=1 Default: 5 seconds

padding

The start/end time of the clips will include some extra padding (in seconds)

Example

GET /rep/search?terms=i+love+you&limit=1&clips&display_fields=f_transcript&clips_include_source_tags=true&max_duration=60&coalescing_span=1&padding=1

Extends the clip start/end time by 1 second Default: 0 seconds