## 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](https://support.google.com/merchants/answer/9967959)
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.

> [!IMPORTANT]
> **Key Point:** If you have never advertised your products or shared them on free listings, you will have no associated metrics and be returned a results field that contains an empty array.

### 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';

> [!IMPORTANT]
> **Key Point:** You must be explicit about the data you want returned. Any wildcards (for example, `Select metrics.*`) will return an error.

#### 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"
          }
        }
    ]}

> [!IMPORTANT]
> **Key Point:** If you don't select any segments in your query, you will only be returned one row of metrics.

### 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"
          }
        }
    ]}

> [!IMPORTANT]
> **Key Point:** Segments can only be selected if metrics are also selected. If you don't select any metrics in your query, you will be returned an error.