# Data Overview

Coupler.io's Google Search Console integration pulls data from the GSC Search Analytics API and URL Inspection API. You select one report type per data flow — performance reports for search clicks and impressions data, or URL inspection for indexing status.

## Available report types

| Report type                                  | Description                                                                                                                        | Typical use case                                         |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| **Search results performance**               | Clicks, impressions, CTR, and average position for Google Search results. Supports dimensions: Date, Country, Device, Page, Query. | SEO dashboards, keyword tracking, page-level performance |
| **Search results performance by appearance** | Same metrics as Search results performance, but automatically grouped by search appearance type (e.g., AMP, Rich result, Video).   | Identifying which search features drive traffic          |
| **Discover performance**                     | Clicks, impressions, CTR, and position for Google Discover. Supports dimensions: Date, Country, Page.                              | Content marketing analysis, Discover traffic trends      |
| **Google News performance**                  | Clicks, impressions, CTR, and position for Google News. Supports dimensions: Date, Country, Device, Page.                          | News content performance, editorial reporting            |
| **URLs index performance**                   | Indexing status, coverage state, crawl details, AMP status, mobile usability, and rich results for a list of specified URLs.       | Technical SEO audits, index coverage monitoring          |

{% hint style="info" %}
The four performance reports (Search results, Search results by appearance, Discover, Google News) share the same core metrics: **clicks**, **impressions**, **ctr**, and **position**. They differ only in the available dimensions and which Google surface they report on.
{% endhint %}

## Metrics and dimensions

### Performance reports (Search results, Discover, Google News)

| Column        | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `siteURL`     | URL of the verified site property                                                |
| `clicks`      | Number of clicks from Google to your site                                        |
| `impressions` | Number of times your site appeared in results                                    |
| `ctr`         | Click-through rate (clicks ÷ impressions). Values range from 0 to 1.0            |
| `position`    | Average ranking position in search results                                       |
| `date`        | Date of the data row (only if Date dimension is selected)                        |
| `country`     | 3-letter ISO 3166-1 alpha-3 country code (only if Country dimension is selected) |
| `device`      | Device type: DESKTOP, MOBILE, or TABLET (only if Device dimension is selected)   |
| `page`        | Page URL (only if Page dimension is selected)                                    |
| `query`       | Search query / keyword (only if Query dimension is selected)                     |

### Search results performance by appearance

| Column        | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| `siteURL`     | URL of the verified site property                                     |
| `keys`        | Search appearance type (e.g., AMP\_TOP\_STORIES, RICH\_RESULT, VIDEO) |
| `clicks`      | Number of clicks                                                      |
| `impressions` | Number of impressions                                                 |
| `ctr`         | Click-through rate                                                    |
| `position`    | Average position                                                      |

### URLs index performance

| Column                              | Description                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| `siteURL`                           | URL of the verified site property                                            |
| `inspectURL`                        | The inspected URL                                                            |
| `inspectionResultLink`              | Link to the inspection result in GSC UI                                      |
| `indexStatusResult.verdict`         | High-level verdict: PASS, NEUTRAL, FAIL, VERDICT\_UNSPECIFIED                |
| `indexStatusResult.coverageState`   | Coverage state: Submitted and indexed, Crawled - currently not indexed, etc. |
| `indexStatusResult.robotsTxtState`  | Whether robots.txt blocks the page                                           |
| `indexStatusResult.indexingState`   | Whether a noindex directive is present                                       |
| `indexStatusResult.lastCrawlTime`   | Last time Google crawled the URL                                             |
| `indexStatusResult.pageFetchState`  | Whether Google could fetch the page                                          |
| `indexStatusResult.googleCanonical` | The canonical URL Google selected                                            |
| `indexStatusResult.userCanonical`   | The canonical URL declared by the page                                       |
| `indexStatusResult.crawledAs`       | Which Googlebot crawler was used                                             |
| `ampResult.verdict`                 | AMP validation verdict                                                       |
| `mobileUsabilityResult.verdict`     | Mobile usability verdict                                                     |
| `richResultsResult.verdict`         | Rich results eligibility verdict                                             |

## Configuration options

#### Sites

Select one or more verified sites to export data from. Each site appears as a separate row group identified by the `siteURL` column. Available for all performance reports (not for URLs index performance — site is inferred from the URL).

#### Report period (Start date / End date)

Define the date range for performance reports. Default is 60 days ago to today. Format: YYYY-MM-DD. Use the date picker to set specific dates.

{% hint style="warning" %}
Google Search Console data has a **processing delay of 2–3 days**. Even with Data state set to "All", the most recent 2–3 days may show incomplete or zero data. Use the **Final** data state for reliable historical analysis.
{% endhint %}

#### Dimensions

Select dimensions to break down your performance data. Available dimensions vary by report type:

| Dimension | Search results | Discover | Google News |
| --------- | -------------- | -------- | ----------- |
| Date      | Yes            | Yes      | Yes         |
| Country   | Yes            | Yes      | Yes         |
| Device    | Yes            | No       | Yes         |
| Page      | Yes            | Yes      | Yes         |
| Query     | Yes            | No       | No          |

{% hint style="info" %}
If no dimensions are selected, the report returns a single aggregated row per site with totals for the entire date range.
{% endhint %}

#### Filters by dimensions

Refine results using dimension filters. You can filter by any dimension, even those not selected as report dimensions. Supported operators:

* **Contains** / **Does not contain** — partial text match
* **Equals** / **Does not equal** — exact match
* **Including Regex** / **Excluding Regex** — regular expression match

{% hint style="info" %}
To find valid values for the **Search appearance** filter, run the **Search results performance by appearance** report first. It returns the list of search appearance types active on your site.
{% endhint %}

#### Search results type

Filter results by search type. Available for Search results performance and Search results performance by appearance:

* **Web** (default)
* **News**
* **Image**
* **Video**

#### Aggregate data by

Control how data is aggregated:

* **Auto** (default) — Google selects the aggregation method automatically
* **Page** — Data is aggregated by canonical URI
* **Property** — All data for the same property is aggregated together
* **News showcase panel** — Aggregates by News Showcase panel (only for Discover and Google News reports; must be used with a Search appearance = NEWS\_SHOWCASE filter)

#### Data state

Control data freshness:

* **Final** (default) — Settled data, several days old, no further changes expected
* **All** — Includes the latest data (up to 24 hours old), which may still change

## Use cases by role

{% tabs %}
{% tab title="SEO" %}
Export Search results performance with Date, Query, and Page dimensions to build keyword ranking dashboards. Track position changes over time, identify queries losing impressions, and find pages that rank but have low CTR. Use dimension filters to focus on branded vs. non-branded queries.
{% endtab %}

{% tab title="Content Marketing" %}
Use the Discover performance report to measure how your articles perform in Google Discover. Track clicks and impressions by page and date to understand which content formats and topics resonate with the Discover audience. Compare Discover traffic alongside Search results data in a combined dashboard.
{% endtab %}

{% tab title="Technical SEO" %}
Export URLs index performance for your key pages to monitor indexing status, crawl issues, canonical conflicts, and mobile usability. Schedule weekly exports to detect indexing regressions. Use the rich results verdict to confirm structured data is being recognized.
{% endtab %}

{% tab title="Editorial / News" %}
Use the Google News performance report to track how your articles perform in Google News. Break down by Date and Country to understand geographic reach. Monitor impression trends to evaluate editorial strategy and content distribution.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Data processing delay** — Google Search Console data is typically delayed by 2–3 days. The most recent dates may show incomplete data even with Data state set to "All". For accurate reporting, use the **Final** data state.
* **16-month data retention** — GSC retains performance data for approximately 16 months. You cannot query data older than this limit.
* **Dimension cardinality** — When using the Query dimension, Google may group low-volume queries under "(other)" if there are too many unique queries. This is a GSC API limitation.
* **CTR and Position are averages** — CTR is clicks ÷ impressions per row. Position is the average ranking. Neither metric is directly summable across dimensions without recalculation.
* **URL inspection quota** — The URL Inspection API has a quota limit. Coupler.io fetches up to 20 URLs concurrently. For large URL lists, the import may take longer.
* **Multiple sites in one flow** — You can select multiple verified sites in a single data flow. Each site's data is identified by the `siteURL` column.