Come uso Search Console + Python per trovare quick wins SEO in 10 minuti

setup — passo 1

# Vai su console.cloud.google.com
# 1. Nuovo progetto → nome: "seo-tools"
# 2. API e servizi → Libreria → cerca "Google Search Console API" → Abilita
# 3. Credenziali → Crea credenziali → Account di servizio
#    Nome: seo-agent
#    Clicca sull'account → tab Chiavi → Aggiungi chiave → JSON
#    Scarica il file service-account.json

# Installa le dipendenze
pip install google-auth google-auth-httplib2 google-api-python-client

gsc_quick_wins.py

from google.oauth2 import service_account
from googleapiclient.discovery import build
from datetime import date, timedelta
import json

# --- CONFIG ---
KEY_FILE = 'service-account.json'
SITE_URL = 'https://tuosito.com/'
SCOPES   = ['https://www.googleapis.com/auth/webmasters.readonly']

# Soglie filtro
MIN_IMPRESSIONS = 3    # ignora keyword con pochissima visibilità
POS_MIN = 6.0          # posizione minima (inclusa)
POS_MAX = 20.0         # posizione massima (inclusa)
DAYS    = 28           # finestra temporale

# CTR atteso per posizione (da usare per stima guadagno)
EXPECTED_CTR = {
    1: 0.28, 2: 0.15, 3: 0.11, 4: 0.08, 5: 0.07,
    6: 0.05, 7: 0.04, 8: 0.03, 9: 0.025, 10: 0.02
}

def get_service():
    creds = service_account.Credentials.from_service_account_file(
        KEY_FILE, scopes=SCOPES)
    return build('searchconsole', 'v1', credentials=creds)

def fetch_queries(service, start_date, end_date):
    """Scarica tutte le query con dimensioni query+page."""
    response = service.searchanalytics().query(
        siteUrl=SITE_URL,
        body={
            'startDate': str(start_date),
            'endDate': str(end_date),
            'dimensions': ['query', 'page'],
            'rowLimit': 5000,
            'orderBy': [{'fieldName': 'impressions', 'sortOrder': 'DESCENDING'}]
        }
    ).execute()
    return response.get('rows', [])

def find_quick_wins(rows, pos_min=POS_MIN, pos_max=POS_MAX, min_imp=MIN_IMPRESSIONS):
    """Filtra e scoreizza le opportunità quick win."""
    opportunities = []
    for row in rows:
        query   = row['keys'][0]
        page    = row['keys'][1]
        clicks  = row['clicks']
        imps    = row['impressions']
        ctr     = row['ctr']
        pos     = row['position']

        # Filtro principale: range posizione + soglia impressioni
        if not (pos_min <= pos <= pos_max) or imps < min_imp:
            continue

        # Stima CTR se arrivasse a top 3
        target_pos = 3
        target_ctr = EXPECTED_CTR.get(target_pos, 0.11)
        estimated_gain = round((target_ctr - ctr) * imps * (28 / 28))

        opportunities.append({
            'query':          query,
            'page':           page.replace(SITE_URL, '/'),
            'position':       round(pos, 1),
            'impressions':    int(imps),
            'clicks':         int(clicks),
            'ctr_actual':     f"{ctr*100:.1f}%",
            'estimated_gain': max(0, estimated_gain)
        })

    # Ordina per traffico guadagnabile (decrescente)
    return sorted(opportunities, key=lambda x: x['estimated_gain'], reverse=True)

def print_report(opportunities):
    print(f"\n{'='*70}")
    print(f"  QUICK WINS SEO — {date.today()}")
    print(f"  Sito: {SITE_URL} | Finestra: {DAYS} giorni")
    print(f"  Filtro: pos {POS_MIN}-{POS_MAX} | min {MIN_IMPRESSIONS} imp")
    print(f"{'='*70}\n")

    if not opportunities:
        print("  Nessun quick win trovato con i filtri attuali.")
        return

    print(f"  {'#':<4} {'QUERY':<40} {'POS':>5} {'IMP':>6} {'CTR':>6} {'GAIN':>6}  PAGINA")
    print(f"  {'-'*80}")
    for i, opp in enumerate(opportunities[:20], 1):
        query_short = opp['query'][:38] + '..' if len(opp['query']) > 38 else opp['query']
        print(f"  {i:<4} {query_short:<40} {opp['position']:>5} "
              f"{opp['impressions']:>6} {opp['ctr_actual']:>6} "
              f"{opp['estimated_gain']:>5}+  {opp['page']}")

    print(f"\n  Totale opportunità trovate: {len(opportunities)}")
    print(f"  Traffico aggiuntivo stimato (top 20): "
          f"+{sum(o['estimated_gain'] for o in opportunities[:20])} clic/mese\n")

def main():
    end   = date.today()
    start = end - timedelta(days=DAYS)

    print(f"Connessione a GSC per {SITE_URL}...")
    service = get_service()
    rows    = fetch_queries(service, start, end)
    print(f"Query scaricate: {len(rows)}")

    opportunities = find_quick_wins(rows)
    print_report(opportunities)

    # Salva anche in JSON per uso downstream
    with open('quick_wins.json', 'w') as f:
        json.dump(opportunities, f, ensure_ascii=False, indent=2)
    print("  Risultati salvati in quick_wins.json")

if __name__ == '__main__':
    main()

crontab — ogni lunedì alle 8:00

# Aggiungi con: crontab -e
0 8 * * 1 cd /path/to/scripts && python3 gsc_quick_wins.py >> logs/quick_wins.log 2>&1

.github/workflows/weekly-gsc.yml

name: Weekly GSC Quick Wins
on:
  schedule:
    - cron: '0 8 * * 1'  # ogni lunedì alle 8:00 UTC
  workflow_dispatch:      # permette anche esecuzione manuale

jobs:
  quick-wins:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install google-auth google-auth-httplib2 google-api-python-client
      - name: Esegui script
        env:
          GSC_SERVICE_ACCOUNT: ${{ secrets.GSC_SERVICE_ACCOUNT }}
        run: |
          echo "$GSC_SERVICE_ACCOUNT" > service-account.json
          python3 gsc_quick_wins.py
      - name: Salva artefatti
        uses: actions/upload-artifact@v4
        with:
          name: quick-wins-${{ github.run_id }}
          path: quick_wins.json

analisi per pagina

def quick_wins_by_page(rows):
    """Raggruppa quick wins per pagina — mostra quali URL ottimizzare."""
    from collections import defaultdict
    pages = defaultdict(lambda: {'queries': [], 'total_imp': 0, 'total_gain': 0})

    for row in rows:
        query = row['keys'][0]
        page  = row['keys'][1].replace(SITE_URL, '/')
        pos   = row['position']
        imps  = row['impressions']

        if not (POS_MIN <= pos <= POS_MAX) or imps < MIN_IMPRESSIONS:
            continue

        target_ctr = 0.11  # pos 3
        gain = max(0, (target_ctr - row['ctr']) * imps)
        pages[page]['queries'].append(query)
        pages[page]['total_imp'] += imps
        pages[page]['total_gain'] += gain

    # Ordina per gain totale
    sorted_pages = sorted(pages.items(),
                          key=lambda x: x[1]['total_gain'], reverse=True)
    for url, data in sorted_pages[:10]:
        print(f"\n  {url}")
        print(f"    Impressioni totali: {int(data['total_imp'])}")
        print(f"    Gain stimato:      +{int(data['total_gain'])} clic/mese")
        print(f"    Query ({len(data['queries'])}): {', '.join(data['queries'][:5])}")

confronto trend

def compare_periods(service):
    end_curr  = date.today()
    start_curr = end_curr - timedelta(days=28)
    end_prev  = start_curr - timedelta(days=1)
    start_prev = end_prev - timedelta(days=28)

    rows_curr = fetch_queries(service, start_curr, end_curr)
    rows_prev = fetch_queries(service, start_prev, end_prev)

    pos_curr = {r['keys'][0]: r['position'] for r in rows_curr}
    pos_prev = {r['keys'][0]: r['position'] for r in rows_prev}

    movements = []
    for query, pos in pos_curr.items():
        if query in pos_prev:
            delta = pos_prev[query] - pos  # positivo = salita
            movements.append({'query': query, 'pos_now': pos,
                               'pos_prev': pos_prev[query], 'delta': delta})

    rising  = sorted([m for m in movements if m['delta'] > 1],
                     key=lambda x: x['delta'], reverse=True)
    falling = sorted([m for m in movements if m['delta'] < -1],
                     key=lambda x: x['delta'])

    print("\n🟢 In salita:")
    for m in rising[:5]:
        print(f"  '{m['query']}' {m['pos_prev']:.1f} → {m['pos_now']:.1f} ({m['delta']:+.1f})")
    print("\n🔴 In discesa:")
    for m in falling[:5]:
        print(f"  '{m['query']}' {m['pos_prev']:.1f} → {m['pos_now']:.1f} ({m['delta']:+.1f})")