Search results

You can sort your search results using the sort_option and group_by parameters. Note that, for each matching video fragment, the API service returns a field named confidence representing the level of confidence that a specific video fragment matches your query.

When you don't specify the group_by parameter, the API service returns your search results as a flat list, sorted on the confidence field in descending order.

When you set the group_by parameter to video, the API service returns your search results grouped by video, sorts the items belonging to each video on the confidence field in descending order, and you can use the sort_option parameter as follows:

  • Set it to clip_count to specify that the API service must determine the number of matching video fragments in each video, and sort the list of videos on that value in descending order.
  • Set it to score to specify that the API service must determine the maximum value of the confidence field for each video, and sort the list of videos on that value in descending order.

Note that the API service doesn't support grouping when using combined queries.

Examples

Although the example code in this guide is written in Python and Node.js, the API is compatible with most programming languages, and you can also use Postman or other REST clients to send requests and view responses.

For a description of each field in the request and response, see the API Reference > Make a search request page.

Prerequisites

The examples in this section assume the following:

  • You’re familiar with the concepts that are described on the Understand page.
  • You've uploaded a video, and the API service has finished indexing it. For details, see the Uploading videos page.

Sorting video fragments

The following example code illustrates the default behavior of the API service. The search results are sorted on the level of confidence in descending order.

headers = {
  "x-api-key": API_KEY
}

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "clip", # This parameter is optional 
  "sort_option": "score" # This parameter is optional
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print(f"Status code: {response.status_code}")
pprint(response.json())
const SEARCH_URL = `${API_URL}/search`

const data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "clip", // This parameter is optional
  "sort_option": "score" // This parameter is optional
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    "headers": {
      "x-api-key": API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following output was truncated for brevity:

Status code: 200
{
  "search_pool": {
    "total_count": 15,
    "total_duration": 10228,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "score": 81.79,
      "start": 117.8359375,
      "end": 125.71875,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "639963a1ce36463e0199c8c7",
      "confidence": "medium"
    },

    {
      "score": 76.8,
      "start": 265.03125,
      "end": 270.5,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "639963a1ce36463e0199c8c7",
      "confidence": "medium"
    },
    {
      "score": 73.74,
      "start": 196.6875,
      "end": 205.78125,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "63b2c707ce36463e0199c906",
      "confidence": "low"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 229,
    "page_expired_at": "2023-01-11T08:33:46Z",
    "next_page_token": "02feedbf-3895-4d5e-b1b3-87497cf1a39c-1"
  }
}

In the example output above, note that the data array contains a list of objects, and each object corresponds to a video fragment that matched your query. The data array is sorted on the value of the score field in descending order.

Sorting videos

When your search results are grouped by vides, you can use the sort_option to sort the list of videos in the response.

Sorting videos on the number of matches

The following example code groups the response by video and sorts the list of videos on the number of matches:

headers = {
  "x-api-key": API_KEY
}

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "video",
  "sort_option": "clip_count"
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print(f"Status code: {response.status_code}")
pprint(response.json())
const SEARCH_URL = `${API_URL}/search`

const data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "video",
  "sort_option": "clip_count"
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    "headers": {
      "x-api-key": API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following output was truncated for brevity:

{
  "search_pool": {
    "total_count": 15,
    "total_duration": 10228,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "clips": [
        {
          "score": 86.69,
          "start": 137.1875,
          "end": 149.1875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "high"
        },
        {
          "score": 85.82,
          "start": 190.2125,
          "end": 193.5625,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "high"
        },
        {
          "score": 48.69,
          "start": 7.96875,
          "end": 11.5,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "low"
        },
        {
          "score": 47.19,
          "start": 752.609375,
          "end": 756.609375,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "low"
        }
      ],
      "id": "63996260ce36463e0199c8c5"
    },
    {
      "clips": [
        {
          "score": 86.14,
          "start": 624.46875,
          "end": 630.46875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996246ce36463e0199c8c4",
          "confidence": "high"
        },
        {
          "score": 85.37,
          "start": 432.46875,
          "end": 442.46875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996246ce36463e0199c8c4",
          "confidence": "high"
        },
        {
          "score": 46.16,
          "start": 293.075,
          "end": 296.8125,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996246ce36463e0199c8c4",
          "confidence": "low"
        }
      ],
      "id": "63996246ce36463e0199c8c4"
    },
    {
      "clips": [
        {
          "score": 83.97,
          "start": 409.95625,
          "end": 417.6375,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b53433ce36463e0199c909",
          "confidence": "high"
        },
        {
          "score": 52.6,
          "start": 562.94375,
          "end": 568.1328125,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b53433ce36463e0199c909",
          "confidence": "low"
        },
        {
          "score": 46.94,
          "start": 312.9625,
          "end": 316.825,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b53433ce36463e0199c909",
          "confidence": "low"
        }
      ],
      "id": "63b53433ce36463e0199c909"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 5,
    "total_inner_matches": 256,
    "page_expired_at": "2023-01-09T12:32:38Z"
  }
}

Note the following about the example output above:

  • The data array contains a list of objects. Each object corresponds to a video and is composed of the following key-value pairs:
    • id: The unique identifier of the video to which the items in the clips array belong.
    • clips: A list of the video fragments that match your search terms.
  • The list of videos is sorted on the number of video fragments in each video in descending order.
  • The video fragments in the clips arrays are sorted on the confidence field in descending order.

Sorting videos on the level of confidence

The following example code groups the response by video and sorts the list of videos on the maximum value of the confidence field:

headers = {
  "x-api-key": API_KEY
}

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "video",
  "sort_option": "score"
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print(f"Status code: {response.status_code}")
pprint(response.json())
const SEARCH_URL = `${API_URL}/search`

const data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "group_by": "video",
  "sort_option": "score"
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    "headers": {
      "x-api-key": API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following output was truncated for brevity:

{
  "search_pool": {
    "total_count": 15,
    "total_duration": 10228,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "clips": [
        {
          "score": 81.79,
          "start": 117.8359375,
          "end": 125.71875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "medium"
        },
        {
          "score": 53.26,
          "start": 203.63125,
          "end": 207.1875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "low"
        },
        {
          "score": 46.69,
          "start": 483.53125,
          "end": 485.53125,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "low"
        }
      ],
      "id": "639963a1ce36463e0199c8c7"
    },
    {
      "clips": [
        {
          "score": 77.29,
          "start": 25.421875,
          "end": 31.375,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b2c707ce36463e0199c906",
          "confidence": "medium"
        },
        {
          "score": 60.67,
          "start": 11.890625,
          "end": 25.421875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b2c707ce36463e0199c906",
          "confidence": "low"
        },
        {
          "score": 46.16,
          "start": 619.59375,
          "end": 623.1875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b2c707ce36463e0199c906",
          "confidence": "low"
        }
      ],
      "id": "63b2c707ce36463e0199c906"
    },
    {
      "clips": [
        {
          "score": 46.29,
          "start": 403.171875,
          "end": 406.25,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963afce36463e0199c8c8",
          "confidence": "low"
        }
      ],
      "id": "639963afce36463e0199c8c8"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 9,
    "total_inner_matches": 229,
    "page_expired_at": "2023-01-11T12:49:15Z"
  }
}

Note the following about the example output above:

  • The data array contains a list of objects. Each object corresponds to a video and is composed of the following key-value pairs:
    • id: The unique identifier of a video to which the items in the clips array belong.
    • clips: A list of the video fragments that match your search terms.
  • The list of videos is sorted on the maximum value of the confidence field in descending order.
  • The video fragments in the clips arrays are sorted on the confidence field in descending order.