Auto-Index — Google Indexing API

Submit URLs to Google for fast indexing via the Google Indexing API.

Prerequisites

Google Cloud Project with the Indexing API enabled
Service Account with a downloaded JSON key file
Google Search Console — add the service account email as an Owner of the property

Environment

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_INDEX_SA_KEY | Yes (or --sa-key) | Absolute path to service account JSON key file |

How to Invoke

Run using uv run with the script's absolute path. The script directory is relative to the skill root.

auto-index — Sitemap diff

Fetches a sitemap, compares against a local cache, and submits only new URLs.

uv run scripts/google_index.py auto-index --sitemap "https://example.com/sitemap.xml"

Force re-index all URLs (ignore cache):

uv run scripts/google_index.py auto-index --sitemap "https://example.com/sitemap.xml" --force

index-now — Submit URL(s) immediately

uv run scripts/google_index.py index-now --url "https://example.com/new-page"

Multiple URLs:

uv run scripts/google_index.py index-now -u "https://example.com/page1" -u "https://example.com/page2"

Notify URL deletion:

uv run scripts/google_index.py index-now --url "https://example.com/old-page" --delete

CLI Reference

auto-index

| Flag | Description | |------|-------------| | --sitemap, -s | (required) Sitemap URL to fetch | | --sa-key, -k | Path to service account JSON key (overrides env) | | --force, -f | Re-index all URLs, ignoring cache |

index-now

| Flag | Description | |------|-------------| | --url, -u | (required) URL to submit — repeatable for multiple URLs | | --sa-key, -k | Path to service account JSON key (overrides env) | | --delete, -d | Notify deletion instead of update |

Output Format

Both commands output structured JSON:

{
  "meta": {
    "action": "auto-index",
    "sitemap": "https://example.com/sitemap.xml",
    "timestamp": "2026-03-02T02:50:00+00:00",
    "total_in_sitemap": 42,
    "new_urls": 5,
    "submitted": 5,
    "success": 5,
    "failed": 0
  },
  "results": [
    {
      "url": "https://example.com/new-page",
      "status": 200,
      "notifyTime": "2026-03-02T02:50:01.123Z"
    }
  ]
}

Cache

Sitemap URL cache is stored at ~/.cache/auto-index/sitemap-cache.json. This allows auto-index to only submit URLs that are new since the last run.

Delete the cache file to reset:

rm ~/.cache/auto-index/sitemap-cache.json

Quota

Google Indexing API allows 200 requests/day. The script auto-caps at this limit and logs a warning if exceeded.

Common Failures

| Error | Fix | |-------|-----| | No service account key provided | Set GOOGLE_INDEX_SA_KEY env or pass --sa-key | | Service account key file not found | Check the file path | | 403 / Permission denied | Ensure the SA email is an Owner in Search Console | | 429 / Quota exceeded | Wait 24h or request quota increase in Cloud Console | | No URLs found in sitemap | Check the sitemap URL is valid and accessible |