Page Search Results

In this topic, you will learn how to implement paging for results of CMS API requests, when the request matches more items than you can return at one time. This allows you to handle large result sets in smaller groups, which improves performance. A maximum of 100 records will be returned from a single request to the CMS API, but for large result sets, we recommend fetching 25 items per request for better performance.

Procedure

To handle data paging, you will follow these steps:

  • Get a count of the total number of records in the result set.
  • Calculate the number of pages for your result set.
  • Loop through and call the CMS API for each page of data.

Get the record count

First, you need to know the total number of videos in your result set. The response in the result set will vary depending on your search criteria. Use the counts resource to return a total count of records in your result set.

Example: Get the total count of videos in your account:

    https://cms.api.brightcove.com/v1/accounts/921483702001/counts/videos

Response:

    {
        "count" : 74
    }

You can also limit the count by using the optional q parameter. For details about using search criteria with this parameter, see the Using the CMS API: Search Videos document.

Example: Here we get the number of videos which have a tag value of wildlife.

    https://cms.api.brightcove.com/v1/accounts/921483702001/counts/videos?q=tags:wildlife

Response:

    {
        "count" : 6
    }

Calculate pages

To calculate the number of pages, take the total number of records in your result set and divide it by the number of records per page (page size).

You can set a fixed page size, or if you are displaying video data to a web page, you can let the user dynamically set the page size (ie., number of video data objects per page).

JavaScript example:

    var numberOfPages = Math.ceil(jsonData.count / pageSize);

Retrieve pages

Loop through the number of pages that you calculated in the previous step and call the CMS API with the limit and offset parameters to retrieve successive subsets of data.

This example returns 10 videos starting with the 21st video in your result set.

    https://cms.api.brightcove.com/v1/accounts/921483702001/videos?limit=10&offset=20

You can also include the optional q parameter. For details about using search criteria with this parameter, see the Using the CMS API: Search Videos document.

This request returns 2 videos starting with the 5th video from the result set of videos which have a tag value of wildlife.

    https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:wildlife&limit=2&offset=4

Known issues

  • Duplicate results: in certain cases, some items in the search results may appear more than once.

    Workaround: to prevent duplicate search results, always use a sort parameter in your search requests.