Paginate query results

  • The Merchant API is the new version of the Content API for Shopping and represents the future of the platform.

  • Merchant Center Query Language supports pagination to handle large result sets using page_size and page_token parameters.

  • The page_size parameter controls the maximum number of rows returned per request, defaulting to 1000.

  • To retrieve subsequent pages of data, use the next_page_token from the previous response as the page_token in the next request.

  • The next_page_token will not be included in the response containing the final batch of rows.

In order to handle result sets containing a large number of rows, Merchant Center Query Language supports pagination. Two parameters are available to control pagination in the reports.search request body: page_size and page_token, in addition to one output field in the response body: next_page_token.

The page_size parameter specifies the maximum number of rows to retrieve in a single request. If unspecified, it is automatically set to the maximum page size of 1000 rows.

The page_token parameter specifies the token of the page to return. If unspecified, the first page is returned. To retrieve a subsequent page, the value received as the next_page_token from the previous reports.search call should be provided as a page_token. When a page_token is provided, all other parameters in the call should match the previous call that returned the page_token to avoid unexpected behavior.

Example:

SELECT
  segments.offer_id,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2021-12-01' AND '2021-12-31'

For this query, assume the account contains 100,000 offer_ids and the page_size is set to 200. The result set will then contain 200 ReportRow objects in the first response, along with a next_page_token.

To retrieve the next 200 rows, send the request again with the same page size, but update the request's page_token to the previous response's next_page_token.

Here is a response body example (the first five results plus the next_page_token):

{
  "results": [
    {
      "segments": {
        "offerId": "12345"
      },
      "metrics": {
        "clicks": "0",
        "impressions": "59",
        "ctr": 0
      }
    },
    {
      "segments": {
        "offerId": "12346"
      },
      "metrics": {
        "clicks": "9625",
        "impressions": "276695",
        "ctr": 0.034785594246372356
      }
    },
    {
      "segments": {
        "offerId": "12347"
      },
      "metrics": {
        "clicks": "148",
        "impressions": "22045",
        "ctr": 0.0067135404853708325
      }
    },
    {
      "segments": {
        "offerId": "12348"
      },
      "metrics": {
        "clicks": "11",
        "impressions": "1100",
        "ctr": 0.01
      }
    },
    {
      "segments": {
        "offerId": "12349"
      },
      "metrics": {
        "clicks": "569",
        "impressions": "62977",
        "ctr": 0.0090350445400701838
      }
    },
    ...
  ],
  "nextPageToken": "CMgB"
}
Previous
Segmentation