Grouping and ungrouping

Grouping and ungrouping refer to the process of organizing the results of a search query in a specific way. The API service 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 API service will group the matching video fragments in the response by video.
  • clip: The matching video fragments in the response will not be grouped.

📘

Note

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

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

Note that, 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.

Prerequisites

  • A valid Twelve Labs account. For details about creating an account and retrieving your API key, see the Authentication page.
  • You’re familiar with the concepts that are described on the Quickstart page.

Grouping items in a response

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

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”
}

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 fragments 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 fragments in the response are not grouped:

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”
}

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.

Related topics