API

Google-Integrations-API (GSC + GA4)

OAuth-Flow, Property-Selection und Daten-Import von Search Console und Analytics.

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	Sofort-Sync der letzten 16 Monate Performance-Daten
GET	`/v1/google/gsc/properties/{p}/metrics`	—	Clicks, Impressions, CTR, Position pro Query/Page/Datum

# 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

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

curl "$BASE/google/ga4/properties/properties%2F123456789/metrics?from=2026-04-01&to=2026-04-30&metrics=sessions,users,conversions" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data'

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

Letzte Aktualisierung: 1. Mai 2026