cuery.seo.keywords

Google Ads API integration for comprehensive keyword research and analysis.

This module provides a streamlined interface to the Google Ads API for keyword planning and research. It enables users to generate keyword ideas, retrieve historical search volume data, and analyze keyword performance metrics across different geographic regions and time periods. The module handles authentication, batching, and data processing to deliver clean, structured keyword data for SEO and content strategy development.

Key features include keyword idea generation from seed keywords or landing pages, historical metrics retrieval with monthly breakdowns, geographic and language targeting, and automated data cleaning and aggregation for analysis workflows.

Useful documentation:

• Keyword ideas:

  • https://developers.google.com/google-ads/api/docs/keyword-planning/generate-keyword-ideas

  • https://developers.google.com/google-ads/api/samples/generate-keyword-ideas

  • https://developers.google.com/google-ads/api/reference/rpc/v20/GenerateKeywordIdeasRequest

• Historical metrics:

  • https://developers.google.com/google-ads/api/docs/keyword-planning/generate-historical-metrics

  • https://developers.google.com/google-ads/api/reference/rpc/v20/GenerateKeywordHistoricalMetricsRequest

• ID/Code references:

  • https://developers.google.com/google-ads/api/data/codes-formats#expandable-7

  • https://developers.google.com/google-ads/api/data/geotargets

• Limits and quotas:

  • https://developers.google.com/google-ads/api/docs/best-practices/quotas

Classes

GoogleKwdConfig

Configuration for Google Ads API access.

Functions

config_from_env()	Load Google Ads API configuration from environment variables.
connect_ads_client()	Load Google Ads client from credentials.
year_month_from_date(date)	Convert a datetime object to a YearMonth string.
is_domain(url)	Check if the URL is a domain only, without path.
fetch_keywords(cfg)	Fetch metrics for a fixed list of keywords or generate keyword ideas from Google Ads API.
collect_columns(df, columns)	Collects values in specified columns into a Series of lists.
collect_volume_columns(df)	Mutates monthly search volume columns into two list columns containing values and dates.
calculate_trend_pct(volumes, n_months)	Calculate trend based on monthly search volumes provided as list.
linreg_trend(y)	Calculate linear regression slope for a list of values.
add_trend_columns(df)	Add trend columns to the DataFrame based on the specified trend type.
process_keywords(response[, collect_volumes, ...])	Process Google Ads API keyword response into a DataFrame.
keywords(cfg)	Fetch and process keywords from Google Ads API based on the provided configuration.

Module Contents

class cuery.seo.keywords.GoogleKwdConfig(/, **data)

Bases: cuery.utils.Configurable

Configuration for Google Ads API access.

Parameters:

data (Any)

keywords: tuple[str, Ellipsis] | None = None

The (initial) keywords to fetch data for. When generating keyword ideas, only the first 20 keywords will be used. Will be ignored in whole-site mode.

url: str | None = None

The page to fetch data for (if applicable). For whole-site mode, provide a pure domain URL (e.g., ‘example.com’).

whole_site: bool = False

Whether to fetch keyword ideas for the whole site (if url is provided).

ideas: bool = False

Whether to expand initial keywords with Google Keyword Planner’s idea generator. Otherwise, will fetch historical metrics for the provided keywords only.

max_ideas: int = None

Maximum number of additional keyword ideas to fetch (if ideas is True).

language: str = ''

The resource name of the language to target. Each keyword belongs to some set of languages; a keyword is included if language is one of its languages. If not set, all keywords will be included. (e.g., ‘en’ for English).

country: str = ''

The geographical target for keyword data (e.g., ‘us’ for United States). If not set, keywords from all locations will be included.

metrics_start: str | None = None

Start date (year and month) for metrics in YYYY-MM format (e.g., ‘2023-01’). Either provide both metrics_start and metrics_end or neither.

metrics_end: str | None = None

End date (year and month) for metrics in YYYY-MM format (e.g., ‘2023-12’). Either provide both metrics_start and metrics_end or neither.

classmethod validate_ideas(ideas, info)

Parameters:

info (pydantic.ValidationInfo)

classmethod validate_language(v)

classmethod validate_country(v)

validate()

cuery.seo.keywords.config_from_env()

Load Google Ads API configuration from environment variables.

Return type:

dict

cuery.seo.keywords.connect_ads_client()

Load Google Ads client from credentials.

Return type:

google.ads.googleads.client.GoogleAdsClient

cuery.seo.keywords.year_month_from_date(date)

Convert a datetime object to a YearMonth string.

Month enum values 0 and 1 are “UNSPECIFIED” and “UNKNOWN”. January is 2 etc.

Parameters:

date (str | datetime.datetime)

Return type:

tuple[int, google.ads.googleads.v20.enums.types.MonthOfYearEnum.MonthOfYear]

cuery.seo.keywords.is_domain(url)

Check if the URL is a domain only, without path.

Parameters:

url (str)

Return type:

bool

cuery.seo.keywords.fetch_keywords(cfg)

Fetch metrics for a fixed list of keywords or generate keyword ideas from Google Ads API.

Parameters:

cfg (GoogleKwdConfig)

Return type:

google.ads.googleads.v20.services.services.keyword_plan_idea_service.pagers.GenerateKeywordIdeasPager | google.ads.googleads.v20.services.GenerateKeywordHistoricalMetricsResponse

cuery.seo.keywords.collect_columns(df, columns)

Collects values in specified columns into a Series of lists.

Parameters:

• df (pandas.DataFrame)

• columns (list[str])

Return type:

pandas.Series

cuery.seo.keywords.collect_volume_columns(df)

Mutates monthly search volume columns into two list columns containing values and dates.

Parameters:

df (pandas.DataFrame)

cuery.seo.keywords.calculate_trend_pct(volumes, n_months)

Calculate trend based on monthly search volumes provided as list.

Parameters:

• volumes (list[float] | numpy.ndarray | None)

• n_months (int)

cuery.seo.keywords.linreg_trend(y)

Calculate linear regression slope for a list of values.

Parameters:

y (list | numpy.ndarray | None)

Return type:

float | None

cuery.seo.keywords.add_trend_columns(df)

Add trend columns to the DataFrame based on the specified trend type.

Parameters:

df (pandas.DataFrame)

Return type:

pandas.DataFrame

cuery.seo.keywords.process_keywords(response, collect_volumes=True, zeros_to_nans=True)

Process Google Ads API keyword response into a DataFrame.

Parameters:

• response (google.ads.googleads.v20.services.services.keyword_plan_idea_service.pagers.GenerateKeywordIdeasPager | google.ads.googleads.v20.services.GenerateKeywordHistoricalMetricsResponse)

• collect_volumes (bool)

• zeros_to_nans (bool)

Return type:

pandas.DataFrame

cuery.seo.keywords.keywords(cfg)

Fetch and process keywords from Google Ads API based on the provided configuration.

Parameters:

cfg (GoogleKwdConfig)

Return type:

pandas.DataFrame