API

Google Integrations API (GSC + GA4)

OAuth flow, property selection, and data import from Search Console and Analytics.

The Google integrations API connects a Rankion account with Google Search Console (GSC), Google Analytics 4 (GA4), and Google Reviews. The OAuth flow itself runs through the web UI (browser redirect to the Google consent screen — Google does not allow a pure API authorization for offline-access scopes), but every follow-up step (list properties, link, pull data) is fully API-capable.

Module context: Google Integrations.

Connections

A connection is the result of a successful OAuth consent — there can be multiple per team (e.g. one account with access to 5 GSC properties).

Method	Endpoint	Description
GET	`/v1/google/connections`	All active connections (email, scopes, status)
DELETE	`/v1/google/connections/{id}`	Disconnect + revoke refresh token

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

GSC — Search Console

Method	Endpoint	Credits	Description
GET	`/v1/google/gsc/properties`	—	All GSC properties across all connected accounts
POST	`/v1/google/gsc/properties/{p}/link`	—	Link property to a Rankion project. Body: `{project_id}`
DELETE	`/v1/google/gsc/properties/{p}/link`	—	Unlink
POST	`/v1/google/gsc/properties/{p}/sync`	1	Immediate sync of the last 16 months of performance data
GET	`/v1/google/gsc/properties/{p}/metrics`	—	Clicks, impressions, CTR, position per query/page/date

# Link a GSC property and run an initial sync
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} is the URL-encoded property identifier — domain properties have the format sc-domain:example.com, URL properties https://example.com/. Both must be URL-encoded (%3A, %2F).

# Read performance metrics
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	Description
GET	`/v1/google/ga4/properties`	All GA4 properties (property ID, stream name, account)
POST	`/v1/google/ga4/properties/{p}/link`	Link. Body: `{project_id}`
DELETE	`/v1/google/ga4/properties/{p}/link`	Unlink
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	Description
GET	`/v1/integrations/google/reviews/status`	Status of the Google Business Profile review connection

The review data itself flows through the Review Sources API — this endpoint just shows whether the auth connection is alive and when the last successful pull was.

Typical flow

1) UI: user clicks "Connect Google" → browser redirect → Google consent → callback
   → Rankion stores refresh token in DB

2) API: GET /google/connections           # shows: connection exists, scopes ok
3) API: GET /google/gsc/properties        # lists what the user granted in GSC
4) API: POST /gsc/properties/{p}/link     # binds property to project
5) API: POST /gsc/properties/{p}/sync     # initial sync (1 credit)
6) API: GET  /gsc/properties/{p}/metrics  # data is ready

Notes

OAuth UI only. Google refuses offline-access refresh tokens for pure API flows without a consent-screen pass. Plan that into your onboarding wizard.
URL-encode the property identifier. Otherwise sc-domain: is interpreted as an unknown scheme part (400).
Sync is async-light. /sync starts a job that, depending on the 16-month volume, runs 30 s – 5 min. last_synced_at in /connections shows the last successful run.
Quota limits still apply. GSC API quota (1200 queries/min/project) is respected by Rankion — on overflow you get a rate-limit error with Retry-After header.
DELETE connection revokes cleanly. The refresh token is revoked at Google; an accidental re-link requires going through the consent flow again.

Letzte Aktualisierung: May 1, 2026