Overview

Reporting API

The Reporting API lets a merchant engage with their performance data programmatically through the Merchant Center Query Language. This is similar to the ability to create custom reports directly in Merchant Center. The Reporting API has the following benefits:

Lets large merchants import performance data for product listings into their internal or third-party reporting systems.
Lets users, third-party partners, and aggregators who manage Merchant Center accounts access reporting.

API users can specify which performance data they would like to retrieve in the Search call response, such as:

Metrics to be returned (for example: Clicks, Impressions)
Dimensions in which to segment the data (for example: OfferId, Date)
Conditions which need to be met (for example: Clicks > 100)

The Reporting API query language can query the Content API for Shopping for performance metrics (clicks, impressions), possibly segmented by various dimensions (reported event attributes like program and date, and product attributes like brand, category, etc.), using the Search method on the Reports service.

The result from a query to the Reports service is a list of ReportRow instances, with each ReportRow representing the values of requested metrics for segments you specified in your query. If no segments are specified, a single row is returned with metrics aggregated across all segments. Otherwise, if any segments are requested alongside metrics, then the response shows one row for each unique segment tuple. It is possible to select multiple segments and multiple metrics in a single query.

Query for metrics

You can query for metrics (Clicks, Impressions, CTR, etc.) that you want returned. You must add a filter on the date range to query the Reports service. The sample query below returns a single row: the aggregate amount of clicks within the added condition of a date range.

SELECT metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-21';

Sample response

The sample JSON code response below shows how this merchant has had 4,440 clicks summed together across all their products across all their destinations between December 1st, 2020 and December 21st, 2020.

{"results": [
    {
      "metrics": {
        "clicks": "4,440"
      }
    }
]}

Query for segments

Alongside metrics, you can also query for segments, which can be an attribute of a product (offer_id, brand, category, etc.) or an attribute of a reported event (date, program). A reported event is an impression or click for a product.

Segments act similarly to a GROUP BY in SQL. Segments split the selected metrics, grouping by each segment in the SELECT clause. The sample query below returns clicks per day, ordered by clicks descending within the added condition of a date range. Only rows where at least one requested metric is non-zero will be returned.

SELECT
  segments.date,
  metrics.clicks
FROM MerchantPerformanceView
WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-03'
ORDER BY metrics.clicks DESC;

Sample response

The sample JSON code response below shows how this merchant has had 1,546 clicks across all their products across all their destinations on December 1st, 2020 and 829 clicks across all their products across all their destinations on December 2nd, 2020. No object will be returned for December 3rd, 2020 since the merchant had no clicks on that day.

{
  "results": [
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 1
        }
      },
      "metrics": {
        "clicks": "1546"
      }
    },
    {
      "segments": {
        "date": {
          "year": 2020,
          "month": 12,
          "day": 2
        }
      },
      "metrics": {
        "clicks": "829"
      }
    }
]}

Query grammar