The Merchant API offers performance reports, for example
[`product_performance_view`](https://developers.google.com/merchant/api/reference/rest/reports_v1/accounts.reports#productperformanceview).
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": "4440"
          }
        }
      ]
    }

> [!IMPORTANT]
> **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](https://developers.google.com/merchant/api/guides/reports/query-language#segments) for
segmentation in [performance
reports](https://developers.google.com/merchant/api/guides/reports/evaluate-products#measure_performance).
For example, querying for `marketing_method` returns a report with a row for
each marketing method, and the
[metrics](https://developers.google.com/merchant/api/guides/reports/query-language#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"
          }
        }
      ]
    }

> [!IMPORTANT]
> **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]
> **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](https://developers.google.com/merchant/api/guides/reports/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](https://support.google.com/merchants/answer/6324436). 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](https://support.google.com/merchants/answer/6324406). 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](https://support.google.com/merchants/answer/7052112) 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`](https://developers.google.com/merchant/api/reference/rest/Shared.Types/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.

For more information about the fields available for query, see [Fields in `productPerformanceView` table](https://developers.google.com/merchant/api/reference/rest/reports_v1/accounts.reports#ProductPerformanceView.FIELDS).