Google Integrations API (GSC + GA4)

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

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

GSC — Search Console

# Link a GSC property: starts the free backfill of the last 90 days
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: fetch a single day (1 credit, no history)
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

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

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 fetches one day only. Each call queues a job for the day three days ago, so it does not bring in older data. History comes from the backfill on linking: 90 days via the API, 30, 90, 180 or 365 days to choose from in the connection wizard. The credit is charged with the 202 response, even if the job fails later.
• 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.

Related: Rank Tracking · Review Sources API · Google Integrations.