Skip to content

AgriciDaniel/claude-blog / skills/blog-google

blog-google

Verified

Credentialed Google API calls for a blog: PageSpeed Insights, CrUX history, Search Console performance and URL Inspection, GA4 organic traffic, Cloud NLP entities, YouTube video search, Google Ads Keyword Planner, and the Indexing API (job and livestream pages only). Uses the user's Google credentials, quotas, and sometimes billing, and asks for consent before the first call. Runs only on an explicit request: /blog google, "run PageSpeed on this blog URL", "pull my Search Console data", "inspect this URL's index status", "set up Google API credentials". Shares config with claude-seo at ~/.config/claude-seo/google-api.json.

scripts/indexing_notify.py

View on GitHub
#!/usr/bin/env python3
"""
Google Indexing API v3 - notify Google of URL updates and removals.

Publishes URL_UPDATED or URL_DELETED notifications. Supports single URL
and batch mode (up to 200 URLs/day). Includes quota tracking.

IMPORTANT: Per Google, "The Indexing API can only be used to crawl pages with
either JobPosting or BroadcastEvent embedded in a VideoObject"
(https://developers.google.com/search/apis/indexing-api/v3/quickstart).
Submitting any other page type is outside the supported use, so submitting
requires the explicit --confirm-eligible flag. --status never needs it.

Usage:
    python indexing_notify.py https://example.com/jobs/123 --confirm-eligible
    python indexing_notify.py https://example.com/jobs/123 --action URL_DELETED --confirm-eligible
    python indexing_notify.py --batch urls.txt --confirm-eligible
    python indexing_notify.py --status https://example.com/jobs/123
"""

import argparse
import json
import sys
import time
from pathlib import Path
from typing import Optional
from urllib.parse import urlparse

try:
    from google_auth import (
        describe_google_api_error, get_oauth_credentials, safe_exception_text, setup_hint,
    )
except ImportError:
    import os
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    from google_auth import (
        describe_google_api_error, get_oauth_credentials, safe_exception_text, setup_hint,
    )

try:
    from googleapiclient.discovery import build
except ImportError:
    print(f"Error: google-api-python-client required. {setup_hint()}", file=sys.stderr)
    sys.exit(1)

INDEXING_SCOPES = ["https://www.googleapis.com/auth/indexing"]
DAILY_QUOTA = 200

SCOPE_WARNING = (
    "NOTE: The Indexing API only supports pages with JobPosting markup or "
    "BroadcastEvent markup embedded in a VideoObject. It is not a general "
    "indexing tool for other page types."
)
CONFIRM_REFUSAL = (
    "Refusing to submit: the Indexing API only supports JobPosting pages and "
    "BroadcastEvent-in-VideoObject pages. Re-run with --confirm-eligible only "
    "if every URL is one of those page types. (--status needs no flag.)"
)


def _status_of(error) -> int | None:
    """HTTP status from a googleapiclient HttpError or equivalent, never from text."""
    for holder in (getattr(error, "resp", None), error):
        for attr in ("status", "status_code", "code"):
            value = getattr(holder, attr, None)
            if isinstance(value, int) and 100 <= value <= 599:
                return value
            if isinstance(value, str) and value.isdigit():
                return int(value)
    return None


def _path_contains_symlink(path: Path, root: Path) -> bool:
    """Return True if path or any existing parent below root is a symlink."""
    current = path if path.exists() or path.is_symlink() else path.parent
    current = current.absolute()
    root = root.absolute()
    while current != current.parent:
        if current.is_symlink():
            return True
        if current == root:
            return False
        current = current.parent
    return False


def _resolve_batch_file(path_value: str) -> Path:
    """Resolve a batch file under the current working directory."""
    root = Path.cwd().resolve()
    candidate = Path(path_value).expanduser()
    if not candidate.is_absolute():
        candidate = root / candidate
    if _path_contains_symlink(candidate, root):
        raise ValueError("Batch file must not use symlinks")
    try:
        resolved = candidate.resolve(strict=True)
    except FileNotFoundError as exc:
        raise ValueError(f"Batch file not found: {path_value}") from exc
    try:
        resolved.relative_to(root)
    except ValueError as exc:
        raise ValueError(f"Refusing to read batch file outside working directory: {path_value}") from exc
    if not resolved.is_file():
        raise ValueError(f"Batch path is not a regular file: {path_value}")
    return resolved


def _validate_url(url: str) -> str:
    """Validate an http or https URL before calling Google APIs."""
    clean = str(url).strip()
    parsed = urlparse(clean)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise ValueError(f"Invalid URL: {url}")
    return clean


def _load_batch_urls(path_value: str) -> list[str]:
    """Load and validate URLs from a cwd-local batch file."""
    path = _resolve_batch_file(path_value)
    urls = []
    with open(path, "r", encoding="utf-8") as f:
        for line_number, line in enumerate(f, 1):
            clean = line.strip()
            if not clean:
                continue
            try:
                urls.append(_validate_url(clean))
            except ValueError as exc:
                raise ValueError(f"Invalid URL on line {line_number}: {clean}") from exc
    return urls


def _exit_error(message: str, as_json: bool) -> None:
    """Emit a CLI error in the requested format."""
    if as_json:
        print(json.dumps({"error": message}, indent=2))
    else:
        print(f"Error: {message}", file=sys.stderr)
    sys.exit(1)


def _build_indexing_service():
    """Build the Indexing API v3 service."""
    credentials = get_oauth_credentials(INDEXING_SCOPES)
    if not credentials:
        return None
    try:
        return build("indexing", "v3", credentials=credentials)
    except Exception as e:
        print(f"Error building Indexing service: {safe_exception_text(e)}", file=sys.stderr)
        return None


def notify_url(
    url: str,
    action: str = "URL_UPDATED",
) -> dict:
    """
    Publish a single URL notification to the Indexing API.

    Args:
        url: The URL to notify about.
        action: 'URL_UPDATED' or 'URL_DELETED'.

    Returns:
        Dictionary with notification result.
    """
    result = {
        "url": url,
        "action": action,
        "notify_time": None,
        "error": None,
    }
    try:
        url = _validate_url(url)
        result["url"] = url
    except ValueError as e:
        result["error"] = str(e)
        return result

    service = _build_indexing_service()
    if not service:
        result["error"] = (
            "Could not build Indexing service. Ensure the service account has "
            "'https://www.googleapis.com/auth/indexing' scope and is added as "
            "Owner in Google Search Console for the target domain."
        )
        return result

    body = {
        "url": url,
        "type": action,
    }

    try:
        response = service.urlNotifications().publish(body=body).execute()
        metadata = response.get("urlNotificationMetadata", {})
        latest = metadata.get("latestUpdate", {}) or metadata.get("latestRemove", {})
        result["notify_time"] = latest.get("notifyTime")
    except Exception as e:
        status = _status_of(e)
        if status == 403:
            result["error"] = describe_google_api_error(
                e, 'Indexing', "Check the service account's Owner access in Google Search Console for this domain."
            )
        elif status == 429:
            result["quota_exceeded"] = True
            result["error"] = (
                f"Quota exceeded. Daily limit: {DAILY_QUOTA} publish requests. "
                "Apply for a quota increase at https://developers.google.com/search/apis/indexing-api/v3/quota-increase"
            )
        elif status == 400:
            result["error"] = f"Invalid URL or request: {describe_google_api_error(e, 'Indexing')}"
        else:
            result["error"] = describe_google_api_error(e, 'Indexing')

    return result


def get_notification_metadata(url: str) -> dict:
    """
    Get the latest notification metadata for a URL.

    Args:
        url: The URL to check.

    Returns:
        Dictionary with latest update and remove timestamps.
    """
    result = {
        "url": url,
        "latest_update": None,
        "latest_remove": None,
        "error": None,
    }
    try:
        url = _validate_url(url)
        result["url"] = url
    except ValueError as e:
        result["error"] = str(e)
        return result

    service = _build_indexing_service()
    if not service:
        result["error"] = "Could not build Indexing service."
        return result

    try:
        response = service.urlNotifications().getMetadata(url=url).execute()
        update = response.get("latestUpdate", {})
        remove = response.get("latestRemove", {})

        if update:
            result["latest_update"] = {
                "url": update.get("url"),
                "type": update.get("type"),
                "notify_time": update.get("notifyTime"),
            }
        if remove:
            result["latest_remove"] = {
                "url": remove.get("url"),
                "type": remove.get("type"),
                "notify_time": remove.get("notifyTime"),
            }
    except Exception as e:
        if _status_of(e) == 404:
            result["error"] = "No notification metadata found for this URL."
        else:
            result["error"] = f"Error fetching metadata: {describe_google_api_error(e, 'Indexing')}"

    return result


def batch_notify(
    urls: list,
    action: str = "URL_UPDATED",
    delay: float = 0.5,
) -> dict:
    """
    Batch notify multiple URLs with quota awareness.

    Args:
        urls: List of URLs.
        action: 'URL_UPDATED' or 'URL_DELETED'.
        delay: Seconds between requests.

    Returns:
        Dictionary with results and quota usage.
    """
    result = {
        "action": action,
        "total": len(urls),
        "results": [],
        "summary": {"success": 0, "error": 0},
        "quota_warning": None,
        "stopped_on_quota": False,
        "not_submitted": [],
        "error": None,
    }

    try:
        urls = [_validate_url(url) for url in urls if str(url).strip()]
    except ValueError as e:
        result["error"] = str(e)
        result["total"] = 0
        return result

    result["total"] = len(urls)

    if len(urls) > DAILY_QUOTA:
        result["quota_warning"] = (
            f"Batch size ({len(urls)}) exceeds daily quota ({DAILY_QUOTA}). "
            f"Only the first {DAILY_QUOTA} URLs will be submitted."
        )
        result["not_submitted"] = list(urls[DAILY_QUOTA:])
        urls = urls[:DAILY_QUOTA]

    if len(urls) > 50:
        result["quota_warning"] = (
            f"Submitting {len(urls)} URLs will use {len(urls)}/{DAILY_QUOTA} "
            f"of your daily quota."
        )

    for i, url in enumerate(urls):
        url = url.strip()
        if not url:
            continue

        print(f"Notifying [{i + 1}/{len(urls)}]: {url}", file=sys.stderr)

        notification = notify_url(url, action)
        result["results"].append(notification)

        if notification.get("error"):
            result["summary"]["error"] += 1
            # Stop on quota exhaustion, classified by HTTP status, not message text.
            if notification.get("quota_exceeded"):
                not_attempted = [u.strip() for u in urls[i + 1:] if u.strip()]
                result["stopped_on_quota"] = True
                result["not_submitted"] = [url] + not_attempted
                result["error"] = (
                    f"Stopped: daily quota exceeded after {result['summary']['success']} "
                    f"successful submissions. {len(result['not_submitted'])} URL(s) were NOT "
                    "submitted (see not_submitted); retry them after the quota resets."
                )
                break
        else:
            result["summary"]["success"] += 1

        if i < len(urls) - 1:
            time.sleep(delay)

    remaining = DAILY_QUOTA - result["summary"]["success"]
    result["estimated_remaining_batch_quota"] = max(0, remaining)
    result["quota_note"] = "Batch-local estimate only. Prior same-day usage is not persisted."

    return result


def main():
    parser = argparse.ArgumentParser(
        description="Google Indexing API v3 - URL notification helper"
    )
    parser.add_argument("url", nargs="?", help="URL to notify")
    parser.add_argument(
        "--action", "-a",
        choices=["URL_UPDATED", "URL_DELETED"],
        default="URL_UPDATED",
        help="Notification type (default: URL_UPDATED)",
    )
    parser.add_argument("--batch", "-b", help="File with URLs (one per line)")
    parser.add_argument("--status", help="Check notification status for a URL")
    parser.add_argument(
        "--delay",
        type=float,
        default=0.5,
        help="Delay between batch requests in seconds (default: 0.5)",
    )
    parser.add_argument(
        "--confirm-eligible",
        action="store_true",
        help=(
            "Required to submit. Confirms every URL is a JobPosting page or a "
            "BroadcastEvent-in-VideoObject page, the only types the Indexing API supports."
        ),
    )
    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")

    args = parser.parse_args()

    if (args.batch or args.url) and not args.status and not args.confirm_eligible:
        _exit_error(CONFIRM_REFUSAL, args.json)

    if args.status:
        result = get_notification_metadata(args.status)
    elif args.batch:
        print(SCOPE_WARNING, file=sys.stderr)
        try:
            urls = _load_batch_urls(args.batch)
        except (OSError, ValueError) as e:
            _exit_error(f"Error reading batch file: {e}", args.json)
        result = batch_notify(urls, args.action, delay=args.delay)
    elif args.url:
        print(SCOPE_WARNING, file=sys.stderr)
        result = notify_url(args.url, args.action)
    else:
        parser.print_help()
        sys.exit(1)

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        if result.get("error"):
            print(f"Error: {result['error']}", file=sys.stderr)

        if args.status:
            print(f"=== Notification Status: {args.status} ===")
            update = result.get("latest_update")
            remove = result.get("latest_remove")
            if update:
                print(f"  Latest Update: {update.get('notify_time')} ({update.get('type')})")
            if remove:
                print(f"  Latest Remove: {remove.get('notify_time')} ({remove.get('type')})")
            if not update and not remove and not result.get("error"):
                print("  No notifications found.")
        elif args.batch:
            summary = result.get("summary", {})
            print(f"=== Batch Indexing Notification ===")
            print(f"Action: {args.action}")
            print(f"Total: {result.get('total', 0)} | Success: {summary.get('success', 0)} | Errors: {summary.get('error', 0)}")
            print(f"Estimated remaining daily quota: {result.get('estimated_remaining_batch_quota', '?')}")
            if result.get("quota_warning"):
                print(f"Warning: {result['quota_warning']}")
            if result.get("not_submitted"):
                print(f"NOT submitted ({len(result['not_submitted'])}):")
                for pending in result["not_submitted"]:
                    print(f"  {pending}")
        else:
            if result.get("notify_time"):
                print(f"Notified: {result['url']} ({result['action']}) at {result['notify_time']}")
            elif not result.get("error"):
                print(f"Notification sent for: {result['url']} ({result['action']})")


if __name__ == "__main__":
    main()
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall