How Do I Automate a Weekly SEO Audit That Emails Me the Wins and Losses?

mkdir -p ~/code/seo-audit && cd ~/code/seo-audit
uv init
uv add google-auth google-api-python-client anthropic resend python-dotenv

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

SITE = "https://yoursite.com/"  # must match GSC property URL exactly
CREDS = "gsc-credentials.json"
SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]


def get_data(days_ago_start: int, days_ago_end: int) -> list[dict]:
    creds = service_account.Credentials.from_service_account_file(
        CREDS, scopes=SCOPES
    )
    service = build("searchconsole", "v1", credentials=creds)

    end = datetime.now() - timedelta(days=days_ago_end)
    start = datetime.now() - timedelta(days=days_ago_start)
    request = {
        "startDate": start.strftime("%Y-%m-%d"),
        "endDate": end.strftime("%Y-%m-%d"),
        "dimensions": ["query", "page"],
        "rowLimit": 1000,
    }
    response = service.searchanalytics().query(
        siteUrl=SITE, body=request
    ).execute()
    return response.get("rows", [])


if __name__ == "__main__":
    current = get_data(days_ago_start=7, days_ago_end=0)
    previous = get_data(days_ago_start=14, days_ago_end=7)
    with open("gsc-current.json", "w") as f:
        json.dump(current, f, indent=2)
    with open("gsc-previous.json", "w") as f:
        json.dump(previous, f, indent=2)
    print(f"Current week: {len(current)} rows")
    print(f"Previous week: {len(previous)} rows")

uv run python pull_gsc.py

import json
import os
import requests
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.environ["AHREFS_API_KEY"]
TARGET = "yoursite.com"

headers = {"Authorization": f"Bearer {TOKEN}"}

def get_domain_rating():
    r = requests.get(
        "https://api.ahrefs.com/v3/site-explorer/domain-rating",
        headers=headers,
        params={"target": TARGET, "date": "today"},
    )
    return r.json()

def get_organic_keywords():
    r = requests.get(
        "https://api.ahrefs.com/v3/site-explorer/organic-keywords",
        headers=headers,
        params={
            "target": TARGET,
            "limit": 100,
            "order_by": "traffic:desc",
        },
    )
    return r.json()

if __name__ == "__main__":
    data = {
        "domain_rating": get_domain_rating(),
        "top_keywords": get_organic_keywords(),
    }
    with open("ahrefs.json", "w") as f:
        json.dump(data, f, indent=2)
    print("Ahrefs data saved.")

import json
import os
from datetime import datetime
from pathlib import Path
from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])


def load_json(path: str) -> str:
    p = Path(path)
    if not p.exists():
        return "not available"
    return p.read_text()


PROMPT_TEMPLATE = """You are writing a weekly SEO report for yoursite.com.
Data sources:

# GSC — current 7 days
{gsc_current}

# GSC — previous 7 days (for comparison)
{gsc_previous}

# Ahrefs
{ahrefs}

Write a Markdown report with this structure:

## Headline
One sentence. The single most important change week-over-week.

## Wins
Up to 5 bullets. Each must reference a specific page or query
and a specific number (impressions, clicks, position).

## Losses
Up to 5 bullets. Same format. Losses are anything that dropped
20%+ in clicks or 3+ positions in ranking.

## What I'd do this week
3 concrete actions, one sentence each. No "monitor" or "review" —
actions must be specific (e.g. "rewrite the H1 on /blog/foo-bar
since it ranks 8 for a query it's better suited to target").

## Cold data table
A Markdown table with the top 10 movers (by absolute change in
clicks), columns: Query, Page, Clicks Δ, Position Δ.

Rules:
- No hype words. No "optimization opportunities." No "leverage."
- Specific numbers. If you don't have the number, don't make one up.
- If a data source is missing, say so at the top and continue.
"""


def main():
    prompt = PROMPT_TEMPLATE.format(
        gsc_current=load_json("gsc-current.json"),
        gsc_previous=load_json("gsc-previous.json"),
        ahrefs=load_json("ahrefs.json"),
    )

    resp = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4000,
        messages=[{"role": "user", "content": prompt}],
    )

    report = resp.content[0].text
    today = datetime.now().strftime("%Y-%m-%d")
    out = Path(f"reports/seo-{today}.md")
    out.parent.mkdir(exist_ok=True)
    out.write_text(report)
    print(f"Report saved: {out}")


if __name__ == "__main__":
    main()

import os
from datetime import datetime
from pathlib import Path
import resend
from dotenv import load_dotenv

load_dotenv()
resend.api_key = os.environ["RESEND_API_KEY"]

today = datetime.now().strftime("%Y-%m-%d")
report = Path(f"reports/seo-{today}.md").read_text()

# Very basic Markdown-to-HTML conversion. For a nicer email, pipe
# through a real Markdown library (markdown-it-py, markdown2).
html = "<pre style='font-family: Menlo, monospace; white-space: pre-wrap;'>" \
       + report.replace("<", "&lt;") \
       + "</pre>"

resend.Emails.send({
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": f"SEO weekly — {today}",
    "html": html,
    "text": report,
})
print("Email sent.")

uv run python send_email.py

#!/bin/bash
cd /Users/you/code/seo-audit
uv run python pull_gsc.py || exit 1
uv run python pull_ahrefs.py || true   # optional source
uv run python write_report.py || exit 1
uv run python send_email.py || exit 1

chmod +x run_weekly.sh

0 6 * * 1 /Users/you/code/seo-audit/run_weekly.sh > /Users/you/code/seo-audit/cron.log 2>&1