Performance reports

The Merchant API offers performance reports, for example product_performance_view. This page explains the structure of performance reports.

Metrics

You can query for metrics (for example, clicks and impressions) that you want returned. You must add a filter on the date range to query the Reports service for performance data.

Here's a sample query that returns a single row, with the total number of clicks within the specified date range:

SELECT clicks
FROM product_performance_view
WHERE date BETWEEN '2023-12-01' AND '2023-12-21'

You must specify the data you want returned. Wildcards (for example, SELECT *) return an error.

The following sample response shows that the merchant has had 4,440 total clicks, across all products, across all marketing methods, between December 1st, 2023 and December 21st, 2023.

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

Key Point: If you don't select any segments fields in your query, you only receive one row of metrics.

Segments

You can use segments fields for segmentation in performance reports. For example, querying for marketing_method returns a report with a row for each marketing method, and the metrics that you specify for that marketing method in the SELECT clause.

Segments fields can be product attributes (for example, offer_id, brand, and category) or event attributes (for example date and marketing_method).

Segments fields act similarly to a GROUP BY in SQL. Segments fields split the selected metrics, grouping by each segment in the SELECT clause.

Here's a sample query that returns clicks per day, in descending order by clicks, within the added condition of a date range. Only rows where at least one requested metric is non-zero are returned.

SELECT
  date,
  clicks
FROM product_performance_view
WHERE date BETWEEN '2023-12-01' AND '2023-12-03'
ORDER BY clicks DESC

The following sample response shows that the merchant had 1,546 clicks across all products, across all marketing methods, on December 1st, 2023, and 829 clicks across all products, across all marketing methods, on December 2nd, 2023. The merchant had no clicks on December 3rd, 2023, so nothing is returned for that date.

{
  "results": [
    {
      "productPerformanceView": {
        "date": {
          "year": 2023,
          "month": 12,
          "day": 1
        },
        "clicks": "1546"
      }
    },
    {
      "productPerformanceView": {
        "date": {
          "year": 2023,
          "month": 12,
          "day": 2
        },
        "clicks": "829"
      }
    }
  ]
}

Key Point: You can only select specific segments fields if you also select metrics. If you don't select any metrics in your query, the Merchant Reports API returns an error.

As with custom reports in the Merchant Center, you can specify multiple segments in the same query with the Merchant Reports API.

Here's a sample query that returns the clicks for all products in your account during a 30-day period, segmented by marketing_method and offer_id:

SELECT marketing_method, offer_id, clicks
FROM product_performance_view
WHERE date BETWEEN '2023-11-01' AND '2023-11-30'

The response from this query includes a row for each combination of offer_id and marketing_method, with the number of clicks for that combination:

{
  "results": [
    {
      "productPerformanceView": {
        "marketingMethod": "ADS",
        "offerId": "12345",
        "clicks": "38"
      }
    },
    {
      "productPerformanceView": {
        "marketingMethod": "ADS",
        "offerId": "12346",
        "clicks": "125"
      }
    },
    {
      "productPerformanceView": {
        "marketingMethod": "ORGANIC",
        "offerId": "12346",
        "clicks": "23"
      }
    },
    {
      "productPerformanceView": {
        "marketingMethod": "ADS",
        "offerId": "12347",
        "clicks": "8"
      }
    },
    {
      "productPerformanceView": {
        "marketingMethod": "ORGANIC",
        "offerId": "12347",
        "clicks": "3"
      }
    }
  ]
}

Caution: Since a new row is returned for each combination of segments fields in your SELECT clause, the total number of rows in your response increases exponentially with each additional segments field.

Category and product type

The Merchant Center Query Language supports segmenting metrics by two groups of attributes that you can define to organize your inventory:

Category levels

Categories from Google's product taxonomy. Google might auto-assign the category to your product if none was provided, or further refine the provided category.

Product type levels

Product types that you assign based on your categorization. Unlike the category levels, there is no predefined set of supported values.

Both the category and product type attributes are organized in a hierarchy with multiple levels. The product specification separates each level with the > character, but you select each level of the hierarchy separately in reports.

For example, consider a product with the following product type levels:

Home & Garden > Kitchen & Dining > Kitchen Appliances > Refrigerators

Reports return each level in its own field:

Segment	Value
product_type_l1	Home & Garden
product_type_l2	Kitchen & Dining
product_type_l3	Kitchen Appliances
product_type_l4	Refrigerators

Currency and price metrics

Price metrics, such as conversion_value, are represented using the Price type. If the metric is available in multiple currencies, the value for each currency is returned in a separate row. For example, the following query:

SELECT conversion_value
FROM product_performance_view
WHERE date = '2023-11-01'

returns the following results:

{
  "results": [
    {
      "productPerformanceView": {
        "conversionValue": {
          "amountMicros": "150000000",
          "currencyCode": "USD"
        }
      }
    },
    {
      "productPerformanceView": {
        "conversionValue": {
          "amountMicros": "70000000",
          "currencyCode": "CAD"
        }
      }
    }
  ]
}

If you request both price and non-price metrics in a query, price metrics are returned in separate result rows from non-price metrics, one result row per currency code. For example, the following query:

SELECT conversions, conversion_value
FROM product_performance_view
WHERE date = '2020-11-01'

returns the following response:

{
  "results": [
    {
      "productPerformanceView": {
        "conversions": "27",
        "conversionValue": {
          "amountMicros": "0",
          "currencyCode": ""
        }
      }
    },
    {
      "productPerformanceView": {
        "conversions": "0",
        "conversionValue": {
          "amountMicros": "150000000",
          "currencyCode": "USD"
        }
      }
    },
    {
      "productPerformanceView": {
        "conversions": "0",
        "conversionValue": {
          "amountMicros": "70000000",
          "currencyCode": "CAD"
        }
      }
    }
  ]
}

All fields you select are returned in the response, even if their value is still the default value or zero.