cuery.seo.keywords ================== .. py:module:: cuery.seo.keywords .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: cuery.seo.keywords.GoogleKwdConfig Functions --------- .. autoapisummary:: cuery.seo.keywords.config_from_env cuery.seo.keywords.connect_ads_client cuery.seo.keywords.year_month_from_date cuery.seo.keywords.is_domain cuery.seo.keywords.fetch_keywords cuery.seo.keywords.collect_columns cuery.seo.keywords.collect_volume_columns cuery.seo.keywords.calculate_trend_pct cuery.seo.keywords.linreg_trend cuery.seo.keywords.add_trend_columns cuery.seo.keywords.process_keywords cuery.seo.keywords.keywords Module Contents --------------- .. py:class:: GoogleKwdConfig(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Configuration for Google Ads API access. .. py:attribute:: keywords :type: tuple[str, Ellipsis] | None :value: 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. .. py:attribute:: url :type: str | None :value: None The page to fetch data for (if applicable). For whole-site mode, provide a pure domain URL (e.g., 'example.com'). .. py:attribute:: whole_site :type: bool :value: False Whether to fetch keyword ideas for the whole site (if `url` is provided). .. py:attribute:: ideas :type: bool :value: False Whether to expand initial keywords with Google Keyword Planner's idea generator. Otherwise, will fetch historical metrics for the provided keywords only. .. py:attribute:: max_ideas :type: int :value: None Maximum number of additional keyword ideas to fetch (if `ideas` is True). .. py:attribute:: language :type: str :value: '' 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). .. py:attribute:: country :type: str :value: '' The geographical target for keyword data (e.g., 'us' for United States). If not set, keywords from all locations will be included. .. py:attribute:: metrics_start :type: str | None :value: 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. .. py:attribute:: metrics_end :type: str | None :value: 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. .. py:method:: validate_ideas(ideas, info) :classmethod: .. py:method:: validate_language(v) :classmethod: .. py:method:: validate_country(v) :classmethod: .. py:method:: validate() .. py:function:: config_from_env() Load Google Ads API configuration from environment variables. .. py:function:: connect_ads_client() Load Google Ads client from credentials. .. py:function:: 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. .. py:function:: is_domain(url) Check if the URL is a domain only, without path. .. py:function:: fetch_keywords(cfg) Fetch metrics for a fixed list of keywords or generate keyword ideas from Google Ads API. .. py:function:: collect_columns(df, columns) Collects values in specified columns into a Series of lists. .. py:function:: collect_volume_columns(df) Mutates monthly search volume columns into two list columns containing values and dates. .. py:function:: calculate_trend_pct(volumes, n_months) Calculate trend based on monthly search volumes provided as list. .. py:function:: linreg_trend(y) Calculate linear regression slope for a list of values. .. py:function:: add_trend_columns(df) Add trend columns to the DataFrame based on the specified trend type. .. py:function:: process_keywords(response, collect_volumes = True, zeros_to_nans = True) Process Google Ads API keyword response into a DataFrame. .. py:function:: keywords(cfg) Fetch and process keywords from Google Ads API based on the provided configuration.