Google-Integrations-API (GSC + GA4)

Die Google-Integrations-API verbindet einen Rankion-Account mit Google Search Console (GSC), Google Analytics 4 (GA4) und Google Reviews. Der OAuth-Flow selbst läuft über die Web-UI (Browser-Redirect zu Google Consent Screen — eine reine API-Authorization ist von Google für offline-access-Scopes nicht freigegeben), aber alle Folge-Schritte (Properties listen, linken, Daten ziehen) sind voll API-fähig.

Modul-Kontext: Google Integrations.

Connections

Eine Connection ist das Resultat eines erfolgreichen OAuth-Consent — pro Team kann es mehrere geben (z.B. ein Account mit Zugriff auf 5 GSC-Properties).

curl "$BASE/google/connections" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, google_email, scopes, last_synced_at}'

GSC — Search Console

# GSC-Property linken + initial syncen
curl -X POST "$BASE/google/gsc/properties/sc-domain%3Aexample.com/link" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_id": 12}'

curl -X POST "$BASE/google/gsc/properties/sc-domain%3Aexample.com/sync" \
  -H "Authorization: Bearer $TOKEN"

{p} ist der URL-encoded Property-Identifier — Domain-Properties haben das Format sc-domain:example.com, URL-Properties https://example.com/. Beide müssen URL-encoded werden (%3A, %2F).

# Performance-Metriken auslesen
curl "$BASE/google/gsc/properties/sc-domain%3Aexample.com/metrics?from=2026-04-01&to=2026-04-30&dimension=query" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {query, clicks, impressions, ctr, position}'

GA4 — Analytics

# Tageswerte
curl "$BASE/google/ga4/properties/123/metrics?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data'

# Besucher aus KI-Suchen je Quelle
curl "$BASE/google/ga4/properties/123/metrics?from=2026-04-01&to=2026-04-30&dimension=ai_source" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data'

{p} ist die Rankion-ID der Property (aus GET /v1/google/ga4/properties). Mit dimension=ai_source kommt je Quelle eine Zeile, sortiert nach Sitzungen:

{ "source": "chatgpt", "sessions": 514, "engaged_sessions": 362, "conversions": 28, "revenue": 976.6 }

source ist chatgpt, perplexity, gemini, copilot, claude, grok oder other_ai (von Google als KI-Assistent gekennzeichnet, Domain unbekannt). Die Zeile other ist die Summe aller übrigen Quellen; der KI-Anteil ist die Summe der KI-Zeilen geteilt durch die Summe aller Zeilen. Google AI Overviews sind in other enthalten, weil GA4 sie nicht von der normalen Google-Suche trennt.

Google Reviews

Die Review-Daten selbst laufen über die Review-Sources-API — dieser Endpoint zeigt nur an, ob die Auth-Anbindung lebt und wann der letzte erfolgreiche Pull war.

Typischer Flow

1) UI: User klickt "Google verbinden" → Browser-Redirect → Google Consent → Callback
   → Rankion speichert Refresh-Token in DB

2) API: GET /google/connections           # zeigt: Connection existiert, scopes ok
3) API: GET /google/gsc/properties        # listet, was der User in GSC freigegeben hat
4) API: POST /gsc/properties/{p}/link     # bindet Property an Projekt
5) API: POST /gsc/properties/{p}/sync     # initial-sync (1 Credit)
6) API: GET  /gsc/properties/{p}/metrics  # Daten liegen bereit

Hinweise

• OAuth nur per UI. Google verweigert offline-access-Refresh-Tokens für reine API-Flows ohne Consent-Screen-Durchlauf. Plane das in deinen Onboarding-Wizard ein.
• Property-Identifier URL-encoden. sc-domain: wird sonst als unbekannter Schemepart interpretiert (400).
• Sync ist async-light. /sync startet einen Job, der je nach 16-Monats-Volumen 30 s – 5 min läuft. last_synced_at in /connections zeigt den letzten erfolgreichen Run.
• Quota-Limits gelten weiter. GSC-API-Quota (1200 Queries/Min/Project) wird von Rankion respektiert — bei Überschreitung Rate-Limit-Fehler mit Retry-After-Header.
• DELETE Connection revokt sauber. Der Refresh-Token wird bei Google revoked; ein versehentlicher Re-Link braucht erneut den Consent-Flow.

Verwandt: Rank-Tracking · Review-Sources-API · Google Integrations.