Pagination
This tutorial describes how to use the Limit and Offset parameters to page through API result sets.
Introduction
Pagination is the process of dividing a total results set into smaller subsets for display in a user-interface.
Limit and offset
The Bazaarvoice platform calculates a total result set each time a request is made using the Conversations API. The total result set can be paginated using the Limit and Offset parameters. Limit controls the count of results that will be returned in response to a request. Offset identifies the position within the total result to start returning results. By combining these two parameters it is possible to iterate through a total result set.
| Parameters | Description |
|---|---|
Limit | Max count of records to return per request. The default is 10 andthe max 100. |
Offset | Index at which to return results. By default, indexing begins at 0 when you issue a query. Using Limit=100&Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000. |
LimitandOffsetare intended for use with organic traffic (users manually clicking links) only. Any other usage will cause performance degradation and may result in restrictions or limitations on API usage.
Basic pagination
The following table demonstrates basic pagination. In this example each page shows the same number of results. The highlighted sections depict the subset that will be returned for a given page.
| Request / Page | Parameters | Total results count |
|---|---|---|
| 1 | &Limit=5&Offset=0 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
| 2 | &Limit=5&Offset=5 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
| 3 | &Limit=5&Offset=10 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
Best practice pagination
As a best practice we recommend displaying less user generated content (UGC) on the first page, and then more after a user has indicated an interest in reading UGC by initiating pagination. Specifically you should display no
fewer than 8 results on the first page and up to 30 results on subsequent pages.
In this example the first page shows a lower number of results than subsequent pages. This is accomplished by modifying the Limit and Offset parameter values. The highlighted sections depict the subset that will be returned for a given page.
| Request / Page | Parameters | Total results count |
|---|---|---|
| 1 | &Limit=5&Offset=0 | 0 1 2 3 45 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
| 2 | &Limit=10&Offset=5 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
| 3 | &Limit=10&Offset=15 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
For simplicity the example above starts with 5 results on the first page and then 10 results on subsequent pages. Our official recommendation is no fewer than 8 results on the first page and then up to 30 results on subsequent pages.
Updated 9 months ago