cuery.seo ========= .. py:module:: cuery.seo .. autoapi-nested-parse:: SEO analysis and keyword research toolkit. This subpackage provides comprehensive tools for SEO research and analysis, integrating data from Google Ads API, Apify web scraping actors, and AI-powered content analysis. It enables users to perform keyword research, analyze SERP results, extract traffic data, and gain insights into search intent and topic clustering for SEO strategy development. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/cuery/seo/aio/index /autoapi/cuery/seo/autocomplete/index /autoapi/cuery/seo/brands/index /autoapi/cuery/seo/funnels/index /autoapi/cuery/seo/geo/index /autoapi/cuery/seo/keywords/index /autoapi/cuery/seo/seo/index /autoapi/cuery/seo/serps/index /autoapi/cuery/seo/sources/index /autoapi/cuery/seo/tools/index /autoapi/cuery/seo/traffic/index Classes ------- .. autoapisummary:: cuery.seo.GoogleKwdConfig cuery.seo.SeoConfig cuery.seo.SerpConfig cuery.seo.TrafficConfig Functions --------- .. autoapisummary:: cuery.seo.seo_data Package 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:class:: SeoConfig(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Configuration for complete keyword data extraction (historical metrics, SERPs, traffic). .. py:attribute:: kwd_cfg :type: cuery.seo.keywords.GoogleKwdConfig Configuration for Google Ads API keyword data extraction. .. py:attribute:: serp_cfg :type: cuery.seo.serps.SerpConfig | None :value: None Configuration for SERP data extraction using Apify Google Search Scraper actor. .. py:attribute:: traffic_cfg :type: cuery.seo.traffic.TrafficConfig | None :value: None Whether and how to fetch traffic data for keywords using Similarweb scraper. .. py:function:: seo_data(cfg) :async: Fetch all supported SEO data types for a given set of keywords. .. py:class:: SerpConfig(/, **data) Bases: :py:obj:`ApifySerpConfig` Configuration for SERP data fetching and analysis. .. py:attribute:: top_n :type: int :value: 10 Number of top organic results to consider for aggregation per keyword. .. py:attribute:: brands :type: str | list[str] | None :value: None List of brand names to identify in SERP data. .. py:attribute:: competitors :type: str | list[str] | None :value: None List of competitor names to identify in SERP data. .. py:attribute:: topic_max_samples :type: int :value: 500 Maximum number of samples to use for topic and intent extraction from SERP data. .. py:attribute:: topic_model :type: str | None :value: 'google/gemini-2.5-flash-preview-05-20' Model to use for topic extraction from SERP organic results. .. py:attribute:: topic_min_ldist :type: int :value: 2 Minimum Levenshtein distance between topic labels. .. py:attribute:: assignment_model :type: str | None :value: 'openai/gpt-4.1-mini' Model to use for intent classification from SERP organic results. .. py:attribute:: entity_model :type: str | None :value: 'openai/gpt-4.1-mini' Model to use for entity extraction from AI overviews. .. py:method:: apify_config() Parameters to pass to the Apify actor. .. py:class:: TrafficConfig(/, **data) Bases: :py:obj:`cuery.utils.Configurable` Configuration for fetching SERP data using Apify Google Search Scraper actor. .. py:attribute:: batch_size :type: int :value: 100 Number of keywords to fetch in a single batch. .. py:attribute:: apify_token :type: str | pathlib.Path | None :value: None Path to Apify API token file. If not provided, will use the `APIFY_TOKEN` environment variable.