Indexing API Google — kompletny tutorial z gotowym skryptem [2026]

Indexing API to oficjalne narzędzie Google do force-crawl URLi — w praktyce działa dla każdego typu strony (mimo że dokumentacja sugeruje "tylko JobPosting"). W tym tutorialu pokazuję setup od zera w 10 minut, gotowy skrypt Python (~30 linii) i case study ze 109 URLi parenting bloga, gdzie 100% zgłoszeń zakończyło się sukcesem.

TL;DR — Indexing API Google w 5 punktach

#	Co	Detale
1. Setup	GCP project + włącz Indexing API + Service Account	5 min
2. GSC	Service Account email jako Owner (NIE Full) w property	1 min
3. Quota	200 requestów/dzień per project	obejście: rozłóż na dni
4. Endpoint	urlNotifications.publish z {url, type: URL_UPDATED}	scope indexing
5. Praktyka	Wspiera każdy URL mimo "officially JobPosting only"	zweryfikowane na 109 URLi

Zamów audyt SEO → jeśli twoja strona ma >100 nieindeksowanych URLi i potrzebujesz strategii force-crawl.

---

Czym jest Indexing API (i dlaczego oficjalna dokumentacja jest myląca)

Indexing API to programowy interfejs Google do informowania Googlebota, że dany URL został zaktualizowany i powinien zostać scrawlowany. Działa analogicznie do funkcji URL Inspection w Google Search Console, ale w trybie bulk — można zgłosić 200 URLi dziennie zamiast pojedynczych klikanych ręcznie.

Ofiicjalny scope vs realny scope

Dokumentacja Google deklaruje:

"The Indexing API allows any site owner to directly notify Google when pages are added or removed. Currently, the Indexing API can only be used to crawl pages with either job posting or broadcast event markup."

Ten cytat zniechęca większość zespołów do użycia API dla bloga, sklepu czy strony usługowej. W praktyce endpoint urlNotifications.publish przyjmuje każdy URL i odpowiada 200 OK. Google nie wymusza w runtime, że zgłaszany URL musi mieć schema JobPosting/BroadcastEvent.

Empiryczne dane (case study dzieckologia.pl, maj 2026)

W naszej sesji dla parenting bloga dzieckologia.pl (Astro 4.16, 53 artykuły PL + 53 EN, świeża domena bez authority) zgłosiliśmy 109 URLi parenting articles + pillar pages przez Indexing API:

• Sukces: 109/109 (100%)
• Type contentu: parenting blog posts (Article schema, NIE JobPosting)
• Endpoint odpowiedzi: wszystkie 200 OK z urlNotificationMetadata
• Wynik po 14 dniach: wzrost indexed URLi z 16% (20/128) do mierzony — pomiar planowany na 2026-05-17

Wniosek empiryczny: Indexing API to faktyczne narzędzie force-crawl dla każdej strony — nie tylko ofert pracy. Oficjalny disclaimer w dokumentacji to prawdopodobnie zabezpieczenie prawne, nie technical limitation.

Kiedy Indexing API ma sens?

Use case	Czy warto?	Dlaczego
Świeża domena (<6 mies.)	✅ TAK	Brak crawl budgetu, sitemap nie wystarcza
Po migracji / rebrandingu	✅ TAK	100+ nowych URLi naraz
Po deployu nowych blogów	✅ TAK	Force-crawl tego samego dnia
Pojedyncze update'y (1-3 URLi)	❌ NIE	URL Inspection w GSC szybsze
Zindeksowane URLe (refresh)	⚠️ Ostrożnie	API to dla nowego contentu, nie multi-week refreshing

---

Setup w 10 minut — krok po kroku

Krok 1: Google Cloud Console — projekt + API

1. Otwórz console.cloud.google.com
2. Utwórz nowy projekt (np. seo-indexing-tools)
3. W menu wybierz APIs & Services → Library
4. Wyszukaj Indexing API i kliknij Enable
5. Zostaniesz przekierowany do panelu API — to potwierdza włączenie

Czas: ~3 min.

Krok 2: Service Account + JSON key

1. Tym razem APIs & Services → Credentials
2. Kliknij Create Credentials → Service Account
3. Nazwa np. seo-indexing-bot, opis dowolny
4. Skip role assignment (nie potrzebujemy roli na poziomie GCP)
5. Po utworzeniu kliknij na Service Account → Keys → Add Key → JSON
6. Plik JSON pobierze się automatycznie. Zachowaj go jako gsc-service-account.json w bezpiecznej lokalizacji (NIE commituj do gita)

Czas: ~2 min. Uwaga: Email Service Account ma format [email protected] — zapisz go, użyjesz w kroku 3.

Krok 3: Google Search Console — Service Account jako Owner

To najczęstszy błąd setupu — większość tutoriali pomija ten krok lub błędnie sugeruje "Full" zamiast "Owner".

1. Otwórz search.google.com/search-console
2. Wybierz property dla której chcesz używać API (np. arduralab.com)
3. Idź do Settings (ikona koła zębatego) → Users and permissions
4. Kliknij Add user
5. Wpisz email Service Account z kroku 2
6. WAŻNE: wybierz Owner, nie Full (Full nie wystarcza dla Indexing API)
7. Zatwierdź

Czas: ~1 min. Po zatwierdzeniu Service Account ma uprawnienia do zgłaszania URLi z tej property.

Krok 4: Test setup — pierwszy request

from google.oauth2 import service_account
from googleapiclient.discovery import build

CREDENTIALS_PATH = "/path/to/gsc-service-account.json"
SCOPES = ["https://www.googleapis.com/auth/indexing"]

credentials = service_account.Credentials.from_service_account_file(
    CREDENTIALS_PATH, scopes=SCOPES
)
service = build("indexing", "v3", credentials=credentials)

response = service.urlNotifications().publish(body={
    "url": "https://twoja-domena.pl/blog/test-url",
    "type": "URL_UPDATED"
}).execute()

print(response)

Oczekiwana odpowiedź:

{
  "urlNotificationMetadata": {
    "url": "https://twoja-domena.pl/blog/test-url",
    "latestUpdate": {
      "url": "https://twoja-domena.pl/blog/test-url",
      "type": "URL_UPDATED",
      "notifyTime": "2026-05-03T20:14:32.123456Z"
    }
  }
}

Najczęstsze błędy:

• 403 Permission denied → Service Account nie jest Ownerem w GSC (krok 3)
• 404 Indexing API not enabled → API nie włączone w GCP (krok 1)
• 400 Invalid argument → URL nieprawidłowy (musi być pełny https://, bez fragmentu #)

---

Skrypt Python ready-to-use (bulk submission z rate limiting)

Skrypt do zgłaszania N URLi z pliku tekstowego, z rate limiting, retry logic i logowaniem do JSON.

#!/usr/bin/env python3
"""Bulk Indexing API request — wzór dla 200 URLi/dzień quota."""
import json
import sys
import time
from datetime import date
from pathlib import Path

from google.oauth2 import service_account
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

CREDENTIALS_PATH = Path("/path/to/gsc-service-account.json")
SCOPES = ["https://www.googleapis.com/auth/indexing"]
RATE_LIMIT_SLEEP = 0.5  # 0.5s między requestami = ~120 req/min
DAILY_QUOTA = 200

def submit_url(service, url: str) -> dict:
    """Zgłaszamy 1 URL z retry on 5xx."""
    body = {"url": url, "type": "URL_UPDATED"}
    for attempt in range(5):
        try:
            return service.urlNotifications().publish(body=body).execute()
        except HttpError as e:
            if e.resp.status >= 500:
                time.sleep(2 ** attempt)
                continue
            raise
    raise RuntimeError(f"Failed after 5 retries: {url}")

def main(urls_file: str) -> None:
    urls = Path(urls_file).read_text().splitlines()
    urls = [u.strip() for u in urls if u.strip() and not u.startswith("#")]

    if len(urls) > DAILY_QUOTA:
        print(f"WARN: {len(urls)} URLs > daily quota {DAILY_QUOTA}. Truncating.")
        urls = urls[:DAILY_QUOTA]

    creds = service_account.Credentials.from_service_account_file(
        CREDENTIALS_PATH, scopes=SCOPES
    )
    service = build("indexing", "v3", credentials=creds, cache_discovery=False)

    results = []
    for i, url in enumerate(urls, 1):
        print(f"[{i}/{len(urls)}] {url}")
        try:
            response = submit_url(service, url)
            results.append({"url": url, "status": "OK", "response": response})
        except Exception as e:
            results.append({"url": url, "status": "ERROR", "error": str(e)})
        time.sleep(RATE_LIMIT_SLEEP)

    log_path = Path(f"indexing-log-{date.today().isoformat()}.json")
    log_path.write_text(json.dumps(results, indent=2))
    ok_count = sum(1 for r in results if r["status"] == "OK")
    print(f"\nDone: {ok_count}/{len(urls)} OK. Log: {log_path}")

if __name__ == "__main__":
    main(sys.argv[1] if len(sys.argv) > 1 else "urls.txt")

Format pliku urls.txt

https://twoja-domena.pl/blog/post-1
https://twoja-domena.pl/blog/post-2
# komentarze są ignorowane
https://twoja-domena.pl/uslugi/seo

Uruchomienie

python3 indexing_bulk.py urls.txt

Output: log JSON z wszystkimi requestami i odpowiedziami. Możesz parsować log do dashboardu lub po prostu sprawdzić, które URL-e zwróciły błąd.

---

Kiedy Indexing API NIE wystarcza

API to nie magic bullet. Otwiera drzwi do crawlu, nie gwarantuje rankingu ani indexacji.

Sytuacje, w których Indexing API nie pomoże

1. Strona ma noindex w meta robots — Google scrawluje, ale nie zaindeksuje. Najpierw napraw <meta name="robots">.
2. Robots.txt blokuje URL — Googlebot nie scrawluje w ogóle. Sprawdź robots.txt.
3. Thin content — Google scrawluje, decyduje że nie warto indeksować. Rozbuduj treść do >800 słów merytorycznych.
4. Duplicate content — Google ignoruje canonical conflict. Skonfiguruj <link rel="canonical">.
5. Domena bez authority — świeże domeny bez backlinków często mają długie crawl delays. Indexing API skraca delay, ale nie eliminuje całkowicie. Patrz nasz BACKLINKS-PLAN.md dla strategii.
6. Wszystkie URLe submitujesz w 1 dniu — Google rate limits crawl, nawet po sygnale z API. Rozłóż 1000+ URLi na 7-14 dni dla efektywnego crawlu.

Komplementarne narzędzia do Indexing API

Narzędzie	Cel	Komplement do Indexing API
Sitemap.xml	Globalna mapa URLi	100% — sitemap mówi GO, API mówi NOW
GSC URL Inspection	Pojedyncze URLe + diagnostyka	100% — różne use case
Internal linking	Crawl path dla nowych URLi	100% — internal links ułatwiają natural crawl
External backlinks	Authority + crawl trigger	100% — backlinki przyspieszają crawl niezależnie
IndexNow (Bing/Yandex)	Notification dla Bing	100% — komplementarny dla Bing

---

FAQ — najczęstsze pytania

Czy mogę używać Indexing API dla strony klienta?

Tak. Service Account musi być Ownerem w GSC property klienta. Wymaga to dostępu klienta lub upoważnienia. Możesz mieć 1 GCP project obsługujący 50+ klientów (1 SA, 50 properties, 200 quota dzielone).

Czy Indexing API pomoże po negative SEO atak?

Częściowo. Po nagłym zniknięciu URLi z indeksu (np. po massive 4xx errors lub manual penalty) — najpierw napraw przyczynę (4xx, content quality, manual action), potem zgłoś przez Indexing API jako URL_UPDATED. API nie naprawia content issues, tylko triggers re-crawl.

Co to type URL_DELETED?

urlNotifications.publish przyjmuje też type: URL_DELETED — informuje Google, że URL został usunięty. Jest to alternatywa dla 410 Gone status code i <meta name="robots" content="noindex">. Praktyczny use case: po usunięciu starych blogów masowo (>50 URLi) chcesz przyspieszyć ich deindexację.

Czy Indexing API liczy się w GSC jako "Submitted via sitemap"?

Nie — w GSC Coverage Report URL submitted via Indexing API pokazuje się w stanie "Submitted and indexed" jeśli zindeksowany, lub "Discovered — currently not indexed" jeśli Google scrawlował ale nie zdecydował zindeksować. Sitemap submission to osobny mechanizm — najlepiej używać obu komplementarnie.

Jak monitorować skuteczność Indexing API?

3 sygnały:

1. Bezpośredni — JSON response z API zawiera latestUpdate.notifyTime (kiedy Google przyjął sygnał)
2. GSC URL Inspection — sprawdź status URLi po 7-14 dniach (PASS = indexed, NEUTRAL = wciąż nie scrawlowany)
3. GSC Performance — czy URLe zaczynają zbierać impresje (= rankują)

Najszybciej sygnał #1 → wolniej #2 → najwolniej #3. Pełny cykl: 1-21 dni dla większości stron.

Czy mogę submitować ten sam URL co tydzień by "boostować" ranking?

Nie. Multi-submission tego samego URLu w krótkim czasie nie boostuje rankingu. API ma sens dla nowego lub istotnie zmienionego contentu. Spam-submission marnuje quota i może obniżyć trust signal.

---

Co dalej

1. Setup ogólny — wykonaj kroki 1-3 raz, nawet jeśli na razie nie używasz API. Setup zajmuje 10 minut, masz to gotowe na każdy przyszły deploy.
2. Integruj w deploy pipeline — po git push automatycznie wywołuj Indexing API dla nowych URLi. CI/CD step na 5 linii bash + Python skrypt powyżej.
3. Re-check po 14 dniach — porównaj GSC Coverage przed i po, mierz delta indexed URLs.
4. Czytaj dalej:
   • Jak przyspieszyć indeksowanie strony — 7 metod (hub artykuł)
   • Sitemap.xml Google — jak zgłosić i przyspieszyć crawl
   • Co to crawling i jak działa Googlebot
   • Crawl budget — co to i jak zwiększyć

---

Zamów audyt SEO

Twoja strona ma 100+ URLi w sitemap, ale tylko 20% indexed? Zamów audyt SEO → — zdiagnozujemy przyczyny (crawl budget, content quality, robots.txt, canonical) i wdrożymy strategię force-indexowania przez Indexing API + komplementarne narzędzia.