Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheCraigHewitt/seomachine/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The GoogleSearchConsole class provides integration with Google Search Console (GSC) to fetch keyword rankings, search performance metrics, and identify SEO opportunities.

​
Installation

from data_sources.modules.google_search_console import GoogleSearchConsole

​
Authentication

The module uses Google service account credentials for authentication.

​
Environment Variables

GSC_SITE_URL=https://yourdomain.com
GSC_CREDENTIALS_PATH=/path/to/credentials.json

​
Service Account Setup

  1. Create a service account in Google Cloud Console
  2. Download the credentials JSON file
  3. Add the service account email as a user in Search Console (with at least “Full” permissions)
  4. Set the credentials path in your environment

​
Initialization

gsc = GoogleSearchConsole(
    site_url="https://castos.com",  # Optional, defaults to env var
    credentials_path="/path/to/credentials.json"  # Optional, defaults to env var
)
​
site_url
str
Site URL (e.g., “https://castos.com”). Defaults to GSC_SITE_URL environment variable.
​
credentials_path
str
Path to service account credentials JSON. Defaults to GSC_CREDENTIALS_PATH environment variable.

​
Methods

​
get_keyword_positions

Get keyword rankings and performance. 
keywords = gsc.get_keyword_positions(
    days=30,
    limit=1000
)
​
days
int
default:"30"
Number of days to analyze
​
limit
int
default:"1000"
Max number of keywords to return
​
results
list
​
keyword
str
Search query
​
clicks
int
Total clicks
​
impressions
int
Total impressions
​
ctr
float
Click-through rate (0-1)
​
position
float
Average position (rounded to 1 decimal)

​
get_quick_wins

Find “quick win” opportunities - keywords ranking 11-20 that are closest to page 1. 
quick_wins = gsc.get_quick_wins(
    days=30,
    position_min=11,
    position_max=20,
    min_impressions=50,
    prioritize_commercial=True
)
​
days
int
default:"30"
Number of days to analyze
​
position_min
int
default:"11"
Minimum position
​
position_max
int
default:"20"
Maximum position
​
min_impressions
int
default:"50"
Minimum impressions threshold
​
prioritize_commercial
bool
default:"true"
Weight score by commercial intent
​
results
list
​
keyword
str
Search query
​
position
float
Average position
​
impressions
int
Total impressions
​
clicks
int
Total clicks
​
commercial_intent
float
Commercial intent score (0.1-3.0)
​
commercial_intent_category
str
“Transactional”, “Commercial Investigation”, “Informational (Relevant)”, or “Informational (Low Value)”
​
opportunity_score
float
Calculated opportunity score
​
priority
str
“high” or “medium”

​
get_page_performance

Get search performance for a specific page. 
page_perf = gsc.get_page_performance(
    url="/blog/podcast-monetization",
    days=30
)
​
url
str
required
Page URL or path
​
days
int
default:"30"
Number of days to analyze
​
page_data
dict
​
url
str
Page URL
​
clicks
int
Total clicks
​
impressions
int
Total impressions
​
ctr
float
CTR percentage
​
avg_position
float
Average position
​
top_keywords
list
Top 10 keywords driving traffic to this page

​
get_low_ctr_pages

Find pages with high impressions but low CTR (need better titles/descriptions). 
low_ctr = gsc.get_low_ctr_pages(
    days=30,
    ctr_threshold=0.03,  # 3%
    min_impressions=100,
    path_filter="/blog/"
)
​
days
int
default:"30"
Number of days to analyze
​
ctr_threshold
float
default:"0.03"
CTR below this is considered low (0.03 = 3%)
​
min_impressions
int
default:"100"
Minimum impressions to consider
​
path_filter
str
Filter by path
​
results
list
​
url
str
Page URL
​
impressions
int
Total impressions
​
clicks
int
Total clicks
​
ctr
float
CTR percentage
​
avg_position
float
Average position
​
potential_clicks
int
Potential clicks at 5% CTR
​
missed_clicks
int
Missed clicks per month
​
priority
str
“high” or “medium”
Find queries gaining traction (rising impressions). 
trending = gsc.get_trending_queries(
    days_recent=7,
    days_comparison=30,
    min_impressions=20
)
​
days_recent
int
default:"7"
Recent period to analyze
​
days_comparison
int
default:"30"
Previous period to compare against
​
min_impressions
int
default:"20"
Minimum impressions in recent period
​
results
list
​
query
str
Search query
​
recent_impressions
int
Impressions in recent period
​
previous_impressions
int
Impressions in comparison period
​
change_percent
float
Percentage change
​
clicks
int
Recent clicks
​
position
float
Current average position

​
get_position_changes

Track keyword position changes over time. 
changes = gsc.get_position_changes(
    days_recent=7,
    days_comparison=30
)
​
days_recent
int
default:"7"
Recent period
​
days_comparison
int
default:"30"
Previous period to compare
​
results
dict
​
improved
list
Keywords that improved by 2+ positions
​
declined
list
Keywords that declined by 2+ positions
​
stable
list
Keywords with minimal position change

​
Commercial Intent Scoring

The module includes built-in commercial intent scoring (_calculate_commercial_intent) that categorizes keywords:
  • High Intent (3.0): Transactional - pricing, buy, vs, alternatives, reviews
  • Medium-High Intent (2.0): Commercial investigation - how to, guide, strategies
  • Medium Intent (1.0): Informational with potential - what is, features, benefits
  • Low Intent (0.1): Pure informational/celebrity - who is, biography, age
See source code at data_sources/modules/google_search_console.py:146

​
Example Usage

from dotenv import load_dotenv
from data_sources.modules.google_search_console import GoogleSearchConsole

load_dotenv('data_sources/config/.env')

gsc = GoogleSearchConsole()

# Quick Win Opportunities
quick_wins = gsc.get_quick_wins()
for i, kw in enumerate(quick_wins[:10], 1):
    print(f"{i}. {kw['keyword']}")
    print(f"   Position: {kw['position']} | Impressions: {kw['impressions']:,}")
    print(f"   Opportunity Score: {kw['opportunity_score']:.1f}")
    print()

# Low CTR Pages
low_ctr = gsc.get_low_ctr_pages()
for page in low_ctr[:5]:
    print(f"- {page['url']}")
    print(f"  {page['impressions']:,} impressions | {page['ctr']:.2f}% CTR")
    print(f"  Missing {page['missed_clicks']} potential clicks")
    print()

# Trending Queries
trending = gsc.get_trending_queries()
for query in trending[:5]:
    print(f"- {query['query']}")
    print(f"  +{query['change_percent']:.1f}% impressions")
    print()

​
Source Code Reference

Location: data_sources/modules/google_search_console.py:16