Guides
SDKsSample appsIntegrationsDiscordPlayground

Grouping and ungrouping

Suggest Edits

Grouping and ungrouping refer to the process of organizing the results of a search query in a specific way. The platform allows for grouping based on the unique identifiers of the videos. For example, this is useful when building a user interface, because it allows your users to better understand and navigate the search results. On the other hand, ungrouping presents your search results in a flat list. This is useful if you want to view all of the search results in a simple manner. Note that this feature can only be used with simple queries.

To group or ungroup items in a response, use the group_by parameter, specifying one of the following values:

  • video: The platform will group the matching video segments in the response by video.
  • clip: The matching video segments in the response will not be grouped.

📘

Note

The group_by parameter is optional and its default value is clip. If omitted, the platform will use the default value. For clarity, the examples in this section always specify the group_by parameter.

Examples

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

Prerequisites

  • You’re familiar with the concepts that are described on the Platform overview page.
  • You’ve uploaded at least one video, and the platform has finished indexing it. For details, see the Upload videos page.

Grouping items in a response

The following example code searches for car accidents, and the matching video segments in the response are grouped by video:

SEARCH_URL = f”{API_URL}/search”

data = {
  “query”: “car accidents”,
  “index_id”: INDEX_ID,
  “search_options”: [“visual”],
  “group_by”: “video”
}

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': 'bear chasing a man',
  'index_id': INDEX_ID,
  'search_options': ['visual'],
  'group_by': 'video'
}

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 has been truncated for brevity:

Status code: 200
{
  "search_pool": {
    "total_count": 13,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "clips": [
        {
          "score": 86.69,
          "start": 137.1875,
          "end": 149.1875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "high",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/138.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T121123Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=77fbecb5fea214120d86e89c144660b20414f0957970621bf299e3d0e261ebec"
        },
        {
          "score": 86.17,
          "start": 173.1875,
          "end": 193.5625,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996260ce36463e0199c8c5",
          "confidence": "high",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/174.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T121123Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=4c2049b56aaa3e1b0aec958fbdce359cd89390830b370cb54f926e77b51c04a2"
        }
      ],
      "id": "63996260ce36463e0199c8c5"
    },
    {
      "clips": [
        {
          "score": 86.14,
          "start": 624.46875,
          "end": 630.46875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996246ce36463e0199c8c4",
          "confidence": "high",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996246ce36463e0199c8c4/625.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T121123Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=8d7d1014ed115ca6b8e76a488662e00afb5d5aad581f8701d0f82785c14c0e56"
        },
        {
          "score": 85.37,
          "start": 432.46875,
          "end": 442.46875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63996246ce36463e0199c8c4",
          "confidence": "high",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996246ce36463e0199c8c4/433.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T121123Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=755fb037c4f6be94583ff261282e35d11b6d0db6af8a6de7bcfc00a63a013bb4"
        }
      ],
      "id": "63996246ce36463e0199c8c4"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 4,
    "total_inner_matches": 32,
    "page_expired_at": "2022-12-29T12:11:23Z"
  }
}

In the example output above, note that the data array contains a list of objects. Each object corresponds to a video that matches your query and is composed of the following key-value pairs:

  • clips: An array that groups the information about all the matching video segments in that video.
  • id: The unique identifier of the video that matched your query.

Ungrouping items in a response

The following example code searches for car accidents, and the matching video segments in the response are not grouped:

SEARCH_URL = f”{API_URL}/search”

data = {
  “query”: “car accidents”,
  “index_id”: INDEX_ID,
  “search_options”: [“visual”],
  “group_by”: “clip”
}

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': 'bear chasing a man',
  'index_id': INDEX_ID,
  'search_options': ['visual'],
  'group_by': 'clip'
}

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": 13,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "score": 86.69,
      "start": 137.1875,
      "end": 149.1875,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/138.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T075204Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=1464a7f7516b5c42669135f7822e1f762f25036c0bb9b1382b40cc7de09188eb"
    },

    {
      "score": 85.4,
      "start": 483.6,
      "end": 498.20625,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "63996232ce36463e0199c8c3",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996232ce36463e0199c8c3/484.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T075204Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=0b7564985d556b65da677719cfedb0fcbf2d8c8fada6af2bc289f6e526d3150d"
    },
    {
      "score": 85.37,
      "start": 432.46875,
      "end": 442.46875,
      "metadata": [
        {
          "type": "visual"
        }
      ],
      "video_id": "63996246ce36463e0199c8c4",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996246ce36463e0199c8c4/433.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221229%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221229T075204Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=d7eae8609413622fe7d2afdd85d40637e9ab0b903a8f7b20d8f85252c5ef5a1d"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 222,
    "page_expired_at": "2022-12-29T07:52:04Z",
    "next_page_token": "52a2c8dc-8ff0-40c6-9a4e-8c2ce56212b3-1"
  }
}

In the example output above, note that the data array contains a list of objects, and each object has a property named video_id, which represents the unique identifier of the video that matched your query.

Updated over 1 year ago