AgriciDaniel/claude-blog / skills/blog-google
blog-google
VerifiedCredentialed 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.2 KB |
| assets/templates/cwv-audit-report.md | markdown | 1.6 KB |
| assets/templates/gsc-performance-report.md | markdown | 1.2 KB |
| assets/templates/indexation-status-report.md | markdown | 1.1 KB |
| references/api-reference.md | markdown | 9.3 KB |
| references/auth-setup.md | markdown | 7.1 KB |
| references/rate-limits-quotas.md | markdown | 4.6 KB |
| references/search-currentness.md | markdown | 12.5 KB |
| scripts/__init__.py | script | 0 B |
| scripts/crux_history.py | script | 11.0 KB |
| scripts/ga4_report.py | script | 17.0 KB |
| scripts/google_auth.py | script | 42.0 KB |
| scripts/google_report.py | script | 37.4 KB |
| scripts/gsc_inspect.py | script | 19.3 KB |
| scripts/gsc_query.py | script | 15.6 KB |
| scripts/indexing_notify.py | script | 15.1 KB |
| scripts/keyword_planner.py | script | 12.0 KB |
| scripts/nlp_analyze.py | script | 19.3 KB |
| scripts/pagespeed_check.py | script | 23.0 KB |
| scripts/requirements.lock | other | 103.0 KB |
| scripts/requirements.txt | manifest | 909 B |
| scripts/run.py | script | 4.2 KB |
| scripts/runtime_paths.py | script | 2.6 KB |
| scripts/setup_environment.py | script | 7.0 KB |
| scripts/youtube_search.py | script | 14.6 KB |
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()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |