Segmentation, available in Merchant Center
[custom reports](https://support.google.com/merchants/answer/9967959), can be
implemented in the Reporting API by adding the appropriate field to a query. For
example, querying for `segments.program` results in a report with a row for each
program (Shopping Ads, Free product listings, etc.) that includes the metrics
(impressions, clicks, etc.) for that program as specified in the `SELECT`
clause.

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

The following sample query retrieves the clicks for all products in your account
during a 30-day period, segmented by `program` and `offer_id`:

    SELECT
      segments.program,
      segments.offer_id,
      metrics.clicks
    FROM MerchantPerformanceView
    WHERE segments.date BETWEEN '2020-11-01' AND '2020-11-30'

[Run](https://developers.google.com/shopping-content/reference/rest/v2.1/reports/search?apix=true&apix_params=%7B%22merchantId%22:0,%22resource%22:%7B%22query%22:%22SELECT++segments.program,++segments.offer_id,++metrics.clicks+FROM+MerchantPerformanceView+WHERE+segments.date+BETWEEN+'2020-11-01'+AND+'2020-11-30'%22%7D%7D)

Click **Run** to try the sample in the **API Explorer** . After you click
**Run** , update the merchant ID placeholder to your own merchant ID in the
request URL. You can modify the query. The full query must remain on one line to
work with the **API explorer**.

The results from sending this query to `reports.search` is a row specifying the
clicks for each combination of `offer_id` and `program`, like in this sample
JSON string:

    {
      "results": [
        {
          "segments": {
            "program": "SHOPPING_ADS",
            "offerId": "12345"
          },
          "metrics": {
            "clicks": "38"
          }
        },
        {
          "segments": {
            "program": "SHOPPING_ADS",
            "offerId": "12346"
          },
          "metrics": {
            "clicks": "125"
          }
        },
        {
          "segments": {
            "program": "FREE_PRODUCT_LISTING",
            "offerId": "12346"
          },
          "metrics": {
            "clicks": "23"
          }
        },
        {
          "segments": {
            "program": "SHOPPING_ADS",
            "offerId": "12347"
          },
          "metrics": {
            "clicks": "8"
          }
        },
        {
          "segments": {
            "program": "FREE_PRODUCT_LISTING",
            "offerId": "12347"
          },
          "metrics": {
            "clicks": "3"
          }
        }
      ]
    }

> [!CAUTION]
> **Caution:** Keep in mind that the number of rows can increase exponentially for each additional segment field included in your report query.

## 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 (`segments.category_l1`, `segments.category_l2`, etc.)
:   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 (`segments.product_type_l1`, `segments.product_type_l2`, etc.)
:   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 will return each level in its own field, as follows:

| Segment | Value |
|---|---|
| `segments.product_type_l1` | `Home & Garden` |
| `segments.product_type_l2` | `Kitchen & Dining` |
| `segments.product_type_l3` | `Kitchen Appliances` |
| `segments.product_type_l4` | `Refrigerators` |

## Currency and price metrics

The `segments.currency_code` field of a `ReportRow` indicates the currency in
which price metrics such as `metrics.conversion_value_micros` are returned.
Since this is important in order to properly interpret these metrics, the
returned `ReportRow` will automatically include `segments.currency_code`
whenever you select one of the price metrics below.

- `metrics.conversion_value_micros`

> [!WARNING]
> **Deprecated:** The following fields are no longer supported.

- `metrics.aov_micros`
- `metrics.ordered_item_sales_micros`
- `metrics.returns_micros`
- `metrics.shipped_item_sales_micros`

> [!NOTE]
> **Note:** You might still want to explicitly include `segments.currency_code` in your query for clarity and consistency between your `SELECT` clause and each `ReportRow` in the response.

## Buy on Google metrics

> [!WARNING]
> **Deprecated:** Buy on Google metrics are no longer supported and retrieving them returns 0 starting from May 2024 (including historical values for past dates).

The Merchant Center Query Language supports two categories of metrics for Buy on
Google orders: item-level metrics and order-level metrics.

item-level metrics

:   Metrics calculated based on the items within orders, and associated with the
    product dimensions of the items in each order.

    - `metrics.item_days_to_ship`
    - `metrics.item_fill_rate`
    - `metrics.ordered_items`
    - `metrics.ordered_item_sales_micros`
    - `metrics.rejected_items`
    - `metrics.returned_items`
    - `metrics.return_rate`
    - `metrics.returns_micros`
    - `metrics.shipped_items`
    - `metrics.shipped_item_sales_micros`
    - `metrics.unshipped_items`

order-level metrics

:   Metrics calculated on a per-order basis.

    - `metrics.aos`
    - `metrics.aov_micros`
    - `metrics.days_to_ship`
    - `metrics.orders`
    - `metrics.shipped_orders`
    - `metrics.unshipped_orders`

:   Order-level metrics are *not* associated with the product dimensions of the
    items in each order.

You can select item-level metrics in combination with any available segment.
However, selecting order-level metrics in combination with any of the following
product dimension segments will fail:

- `segments.brand`
- `segments.category_l1`, `segments.category_l2`, `segments.category_l3`, `segments.category_l4`, `segments.category_l5`
- `segments.custom_label1`, `segments.custom_label2`, `segments.custom_label3`, `segments.custom_label4`, `segments.custom_label5`
- `segments.offer_id`
- `segments.product_type_l1`, `segments.product_type_l2`, `segments.product_type_l3`, `segments.product_type_l4`, `segments.product_type_l5`
- `segments.title`

## Find out more

For a complete list of segments, check out the
[documentation](https://developers.google.com/shopping-content/reference/rest/v2.1/reports/search#segments).