> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Google Search Console data source in Adriel.

## Introduction

Google Search Console reports how a website performs in Google's organic (unpaid) search results. It measures the clicks, impressions, click-through rate, and average position for the queries, pages, and countries that surface a property in Search — the core signals for tracking SEO and organic-search visibility.

The connector reads from Google's Search Analytics API (Webmasters API v3). One data source is created per verified property; a property can be a domain property (covering every subdomain and protocol) or a URL-prefix property (a single scheme and host). Connecting three properties produces three independent data sources.

As an analytics connector, search-performance metrics and breakdowns are standardized so widgets can aggregate alongside ad-platform and web-analytics sources without additional configuration. To connect this data source, see [How to connect Google Search Console to Adriel](/data-sources/g-n/google-search-console/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture for this connector is the list of verified properties available to the connected Google account. Adriel reads that list at connection time so a property can be selected as the data source, and re-checks access on use: if a property is no longer in the account's verified list, or is only accessible as an unverified user, the affected data source is disconnected.

Search Console has no campaign or ad hierarchy, so there is no scheduled architecture snapshot beyond this property-level access check.

### Reports data

Reports data is fetched **on demand**. Each dashboard load issues a live request to the Search Analytics API for the selected date range, breakdowns, metrics, and filters — there is no nightly snapshot or fixed refresh window, and results are not cached. Returned rows reflect Search Console's current processing state; the most recent data is preliminary and may still change as Search Console finalizes processing.

## Architecture levels

Property (domain or URL-prefix)

Search Console has no ad-hierarchy analog. The verified property is the reporting boundary, and each Adriel data source maps to exactly one property.

## Date range limits

For date breakdowns, the connector enforces these maximum look-back windows to keep query sizes manageable. Ranges beyond the cap are truncated.

| Breakdown | Max range |
| --------- | --------- |
| Daily     | 93 days   |
| Weekly    | 1 year    |

Search Console retains roughly 16 months of history overall; data older than that cannot be retrieved through the API (see Limitations).

## Metrics

<Note>
  **How to read the columns**

  Code style like `searchConsole:clicks` is the literal field requested from the Search Analytics API. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field or when it's computed by Adriel.

  **Data type vocabulary**: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
</Note>

### Search performance

| Metric      | Description                                                                                                                                                                                | Data type  | API Key                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | --------------------------- |
| Clicks      | Count of clicks from a Google Search result that landed a user on the property.                                                                                                            | Number     | `searchConsole:clicks`      |
| Impressions | How many times links to the property appeared in Google Search results. An impression is counted when the user visits that page of results, even if the result was not scrolled into view. | Number     | `searchConsole:impressions` |
| CTR         | Click-through rate: clicks divided by impressions. Rows with no impressions show a dash (-) rather than dividing by zero.                                                                  | Percentage | `searchConsole:ctr`         |
| Position    | Average position of the property's topmost result in Search. When grouped by query, this is the average position for that query.                                                           | Number     | `searchConsole:position`    |

<Note>
  **CTR is recomputed for aggregation**

  When CTR is requested, Adriel automatically fetches clicks and impressions alongside it and recomputes CTR as clicks ÷ impressions across the aggregated rows. This keeps totals and subtotals accurate rather than averaging pre-computed per-row rates.
</Note>

## Breakdowns

<Note>
  **How to read the columns**

  Code style like `searchConsole:query` is the literal breakdown field requested from the Search Analytics API. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field or when it's produced by Adriel.
</Note>

### Search performance

| Breakdown         | Description                                                                                          | API Key                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------- |
| Query             | The search query string a user typed in Google Search that led to an impression of the page.         | `searchConsole:query`            |
| Page              | The landing page URL where the user arrived from Google Search results.                              | `searchConsole:page`             |
| Device            | The device category the search traffic came from: DESKTOP, MOBILE, or TABLET.                        | `searchConsole:device`           |
| Country           | The country the search traffic originated from, based on the user's IP address (ISO 3166-1 alpha-2). | `searchConsole:country`          |
| Search appearance | The type of search-result appearance, such as WEB, AMP\_BLUE\_LINK, RICH\_RESULTS, or VIDEO.         | `searchConsole:searchAppearance` |

<Note>
  At most one of these breakdowns may be combined with one date breakdown per query. Search appearance is the exception: it may only be used on its own (with or without a date breakdown) and cannot be paired with another search-performance breakdown.
</Note>

### Time & date grouping

<Note>
  Adriel groups Search Console's results into these standard views for reporting alongside other connectors.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| No grouping         | Return aggregate totals with no time split.                  |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split reports by day.                                        |
| Weekly (Start: Mon) | Split reports by ISO week, starting Monday.                  |
| Monthly             | Split reports by calendar month.                             |
| Quarterly           | Split reports by calendar quarter.                           |
| Yearly              | Split reports by calendar year.                              |
| Datasource Name     | Group by the name of the Adriel data source.                 |

## Limitations

Based on the current connector, Google Search Console has:

* **A 50,000-row cap per property per day (per search type)** — Adriel fetches results in two pages of up to 25,000 rows each. When both pages return exactly 25,000 rows the query is treated as over-limit (`TOO_MUCH_DATA_REQUESTED`) and no partial data is returned.
* **Reduced coverage on multi-breakdown queries** — requesting several breakdowns together (for example query + page + country) increases query load, and some rows may be aggregated or filtered out by Search Console, leading to missing data.
* **A single non-date breakdown per query** — only one search-performance breakdown may combine with one date breakdown; search appearance cannot be combined with any other search-performance breakdown.
* **Roughly 16 months of history** — Search Console retains about 16 months of data; older ranges cannot be retrieved through the API.
* **A short data-finalization delay** — the connector is real-time and uncached, so the most recent data is preliminary and may still change as Search Console finalizes processing.
* **A per-property rate limit of 3 requests per second** — higher request volumes are queued and processed sequentially.
* **Read-only access** — the connector requests the `webmasters.readonly` scope and cannot write back to Search Console.
* **One property per data source** — each Adriel data source maps to a single verified domain or URL-prefix property.

## API references

* [Search Console API — Search Analytics: query](https://developers.google.com/webmaster-tools/v1/searchanalytics/query)
* [Search Console API overview](https://developers.google.com/webmaster-tools/about)
* [Search Console API — Sites resource](https://developers.google.com/webmaster-tools/v1/sites)

## See also

* [How to connect Google Search Console](/data-sources/g-n/google-search-console/how-to-connect) (paired how-to)
* [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference) — for on-site web and app analytics
* [Semrush data reference](/data-sources/o-z/semrush/data-reference) — for competitive and off-site SEO metrics