> ## 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 Keyword Planner data source in Adriel.

## Introduction

Google Keyword Planner is Google Ads' keyword research tool. It returns search-volume estimates, competition levels, and bid-range suggestions for a set of seed keywords, sourced from Google's search query data. This connector queries the Google Ads Keyword Planner API on behalf of a connected Google Ads account and stores the results in a per-asset cache for reporting in Adriel widgets.

Unlike ad-platform reporting connectors, Keyword Planner returns **market-research indicators** rather than delivery metrics — there is no spend, click, or conversion data. Metrics are best suited to research widgets and content-planning dashboards.

To connect this data source, see [How to connect Google Keyword Planner to Adriel](/data-sources/g-n/google-keyword-planner/how-to-connect).

## Data refresh strategy

### Architecture data

This connector does not import a campaign hierarchy. Each Adriel asset represents one Keyword Planner query configuration (seed keywords, target location, network, and timeframe).

### Reports data

Adriel re-queries the Google Ads Keyword Planner API on a scheduled cadence and stores the returned rows in the per-asset Postgres cache table `GKP_{assetId}`.

**Refresh schedule.** Daily at a fixed UTC hour (pending tech reviewer confirmation).

**Refresh strategy.** The cache is rewritten in full on each successful run.

## Metrics

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

  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

  **API Key** in code style is the literal Google Ads API field name from the Keyword Planner service.
</Note>

### Keywords

| Metric  | Description              | Data type | API Key |
| ------- | ------------------------ | --------- | ------- |
| Keyword | The keyword text itself. | Text      | `text`  |

### Search volume

| Metric                   | Description                                                                                                                                 | Data type | API Key                |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------- |
| Average monthly searches | Average number of times the keyword is searched per month over the selected timeframe. Low-volume keywords are returned in bucketed ranges. | Number    | `avg_monthly_searches` |

### Competition

| Metric            | Description                                                                    | Data type | API Key             |
| ----------------- | ------------------------------------------------------------------------------ | --------- | ------------------- |
| Competition level | Google's categorical competition rating for the keyword (LOW / MEDIUM / HIGH). | Text      | `competition`       |
| Competition index | Numeric competition indicator on a 0–100 scale.                                | Number    | `competition_index` |

### Bid estimates

| Metric                 | Description                                                                            | Data type | API Key                       |
| ---------------------- | -------------------------------------------------------------------------------------- | --------- | ----------------------------- |
| Top-of-page bid (low)  | Low-end estimate of the bid required to appear at the top of the search results page.  | Currency  | `low_top_of_page_bid_micros`  |
| Top-of-page bid (high) | High-end estimate of the bid required to appear at the top of the search results page. | Currency  | `high_top_of_page_bid_micros` |

## Breakdowns

### Keyword & targeting

| Breakdown          | Description                                                             | API Key                |
| ------------------ | ----------------------------------------------------------------------- | ---------------------- |
| Keyword            | Group by keyword text.                                                  | `text`                 |
| Network            | Query network — Google Search only, or Google Search + Search Partners. | `keyword_plan_network` |
| Country / Location | Target location (country or geo-target constant).                       | `geo_target_constants` |

### Time & grouping

<Note>
  Adriel-provided breakdowns are produced by Adriel from the returned data rather than by the Keyword Planner API.
</Note>

| Breakdown   | Description                                                                                              |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| Monthly     | Split search-volume data by month (Adriel groups the monthly search-volume series into calendar months). |
| No Grouping | Do not break down; return one aggregated row per keyword.                                                |

## Limitations

* **Search-volume estimates.** Keyword Planner returns estimated monthly searches; for lower-volume keywords these are presented as ranges rather than exact counts.
* **No delivery metrics.** Keyword Planner returns market indicators only — there are no impressions, clicks, cost, or conversion metrics from this connector.
* **Bid ranges, not average CPCs.** Bid values are top-of-page bid ranges (low / high), not observed CPCs from live campaigns.
* **Account eligibility.** The connected Google Ads account must have access to the Keyword Planner tool; new or inactive accounts may return restricted data.
* **Timeframe granularity.** Search-volume data is aggregated at the monthly level; sub-monthly trends are not available.

## API references

* [Google Ads API — KeywordPlanIdeaService](https://developers.google.com/google-ads/api/reference/rpc/latest/KeywordPlanIdeaService)
* [Google Ads API — KeywordPlanNetwork enum](https://developers.google.com/google-ads/api/reference/rpc/latest/KeywordPlanNetworkEnum.KeywordPlanNetwork)
* [Keyword Planner Help](https://support.google.com/google-ads/answer/7337243)

## See also

* [How to connect Google Keyword Planner](/data-sources/g-n/google-keyword-planner/how-to-connect) (paired how-to)
* [Google Trends data reference](/data-sources/g-n/google-trends/data-reference) — for search-trend index over time
* [Google Search Console data reference](/data-sources/g-n/google-search-console/data-reference) — for actual search-impression and click data on owned properties