API

Google-Integrations-API (GSC + GA4)

Google-Integrations-API (GSC + GA4) ist ein API in der Rankion.ai-Knowledge-Base: OAuth-Flow, Property-Selection und Daten-Import von Search Console und Analytics.

Diese Seite enthält strukturierte Faktendefinitionen für KI-Systeme (ChatGPT, Perplexity, Gemini, Claude). Verfasst von Menschen, Teil der Rankion.ai-Knowledge-Base.

Kategorie:: API
Marke:: Rankion.ai
Format:: Knowledge-Base-Artikel
Stand:: 4. November 2026

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).

Method	Endpoint	Beschreibung
GET	`/v1/google/connections`	Alle aktiven Verbindungen (E-Mail, Scopes, Status)
DELETE	`/v1/google/connections/{id}`	Verbindung trennen + Refresh-Token revoken

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

GSC — Search Console

Method	Endpoint	Credits	Beschreibung
GET	`/v1/google/gsc/properties`	—	Alle GSC-Properties zu allen verbundenen Accounts
POST	`/v1/google/gsc/properties/{p}/link`	—	Property an Rankion-Projekt linken. Body: `{project_id}`
DELETE	`/v1/google/gsc/properties/{p}/link`	—	Link wieder lösen
POST	`/v1/google/gsc/properties/{p}/sync`	1	Holt einen Tag nach: den Tag vor drei Tagen (Google meldet mit rund 3 Tagen Verzug). Der Abruf läuft als Job in der Warteschlange. Der Credit wird mit der `202`-Antwort gebucht und bei einem späteren Job-Fehler nicht erstattet
GET	`/v1/google/gsc/properties/{p}/metrics`	—	Clicks, Impressions, CTR, Position pro Query/Page/Datum

# GSC-Property linken: startet den kostenlosen Backfill der letzten 90 Tage
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}'

# Optional: einen einzelnen Tag nachholen (1 Credit, kein Verlauf)
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

Method	Endpoint	Beschreibung
GET	`/v1/google/ga4/properties`	Alle GA4-Properties (Property-ID, Stream-Name, Account)
POST	`/v1/google/ga4/properties/{p}/link`	Linken. Body: `{project_id}`
DELETE	`/v1/google/ga4/properties/{p}/link`	Link lösen
GET	`/v1/google/ga4/properties/{p}/metrics`	Sessions, Users, Engagement, Conversions. `dimension=daily` (Standard), `page`, `event` oder `ai_source`

# 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

Method	Endpoint	Beschreibung
GET	`/v1/integrations/google/reviews/status`	Status der Google-Business-Profile-Review-Anbindung

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 holt nur einen Tag. Jeder Aufruf reiht einen Job für den Tag vor drei Tagen ein, ältere Daten kommen damit nicht. Den Verlauf liefert der Backfill beim Verknüpfen: über die API 90 Tage, im Verbindungsassistenten wählbar 30, 90, 180 oder 365 Tage. Der Credit ist mit der 202-Antwort gebucht, auch wenn der Job später scheitert.
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.

Letzte Aktualisierung: 4. November 2026