cuery.seo#

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#

Classes#

GoogleKwdConfig

Configuration for Google Ads API access.

SeoConfig

Configuration for complete keyword data extraction (historical metrics, SERPs, traffic).

SerpConfig

Configuration for SERP data fetching and analysis.

TrafficConfig

Configuration for fetching SERP data using Apify Google Search Scraper actor.

Functions#

seo_data(cfg)

Fetch all supported SEO data types for a given set of keywords.

Package Contents#

class cuery.seo.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()#
class cuery.seo.SeoConfig(/, **data)#

Bases: cuery.utils.Configurable

Configuration for complete keyword data extraction (historical metrics, SERPs, traffic).

Parameters:

data (Any)

kwd_cfg: cuery.seo.keywords.GoogleKwdConfig#

Configuration for Google Ads API keyword data extraction.

serp_cfg: cuery.seo.serps.SerpConfig | None = None#

Configuration for SERP data extraction using Apify Google Search Scraper actor.

traffic_cfg: cuery.seo.traffic.TrafficConfig | None = None#

Whether and how to fetch traffic data for keywords using Similarweb scraper.

async cuery.seo.seo_data(cfg)#

Fetch all supported SEO data types for a given set of keywords.

Parameters:

cfg (SeoConfig)

Return type:

pandas.DataFrame

class cuery.seo.SerpConfig(/, **data)#

Bases: ApifySerpConfig

Configuration for SERP data fetching and analysis.

Parameters:

data (Any)

top_n: int = 10#

Number of top organic results to consider for aggregation per keyword.

brands: str | list[str] | None = None#

List of brand names to identify in SERP data.

competitors: str | list[str] | None = None#

List of competitor names to identify in SERP data.

topic_max_samples: int = 500#

Maximum number of samples to use for topic and intent extraction from SERP data.

topic_model: str | None = 'google/gemini-2.5-flash-preview-05-20'#

Model to use for topic extraction from SERP organic results.

topic_min_ldist: int = 2#

Minimum Levenshtein distance between topic labels.

assignment_model: str | None = 'openai/gpt-4.1-mini'#

Model to use for intent classification from SERP organic results.

entity_model: str | None = 'openai/gpt-4.1-mini'#

Model to use for entity extraction from AI overviews.

apify_config()#

Parameters to pass to the Apify actor.

Return type:

ApifySerpConfig

class cuery.seo.TrafficConfig(/, **data)#

Bases: cuery.utils.Configurable

Configuration for fetching SERP data using Apify Google Search Scraper actor.

Parameters:

data (Any)

batch_size: int = 100#

Number of keywords to fetch in a single batch.

apify_token: str | pathlib.Path | None = None#

Path to Apify API token file. If not provided, will use the APIFY_TOKEN environment variable.