API de Google Integrations (GSC + GA4)
API de Google Integrations (GSC + GA4) ist ein API in der Rankion.ai-Knowledge-Base: OAuth flow, selección de propiedades e importación de datos de Search Console y 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:
La API de Google Integrations conecta una cuenta Rankion con Google Search Console (GSC), Google Analytics 4 (GA4) y Google Reviews. El propio OAuth flow corre por la UI web (redirect del navegador a la pantalla de consent de Google — Google no autoriza una autorización puramente API para scopes de offline access), pero todos los pasos posteriores (listar properties, linkearlas, traer datos) son totalmente API-capaces.
Contexto del módulo: Google Integrations.
Connections
Una connection es el resultado de un consent OAuth exitoso — por team puede haber varias (p. ej. una cuenta con acceso a 5 GSC properties).
| Method | Endpoint | Descripción |
|---|---|---|
| GET | /v1/google/connections |
Todas las conexiones activas (e-mail, scopes, status) |
| DELETE | /v1/google/connections/{id} |
Desconectar + revocar refresh token |
curl "$BASE/google/connections" -H "Authorization: Bearer $TOKEN" \
| jq '.data[] | {id, google_email, scopes, last_synced_at}'
GSC — Search Console
| Method | Endpoint | Créditos | Descripción |
|---|---|---|---|
| GET | /v1/google/gsc/properties |
— | Todas las GSC properties de todas las cuentas conectadas |
| POST | /v1/google/gsc/properties/{p}/link |
— | Linkear property a un proyecto Rankion. Body: {project_id} |
| DELETE | /v1/google/gsc/properties/{p}/link |
— | Deshacer el link |
| POST | /v1/google/gsc/properties/{p}/sync |
1 | Sync inmediato de los últimos 16 meses de datos de performance |
| GET | /v1/google/gsc/properties/{p}/metrics |
— | Clicks, impressions, CTR, position por query/page/fecha |
# Linkear GSC property + sync inicial
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} es el identificador de property URL-encoded — las domain properties tienen el formato sc-domain:example.com, las URL properties https://example.com/. Ambas deben ir URL-encoded (%3A, %2F).
# Leer métricas de performance
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 | Descripción |
|---|---|---|
| GET | /v1/google/ga4/properties |
Todas las GA4 properties (Property ID, Stream Name, Account) |
| POST | /v1/google/ga4/properties/{p}/link |
Linkear. Body: {project_id} |
| DELETE | /v1/google/ga4/properties/{p}/link |
Deshacer link |
| 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 | Descripción |
|---|---|---|
| GET | /v1/integrations/google/reviews/status |
Estado de la integración Google Business Profile Review |
Los datos de reviews en sí van por la API de Review Sources — este endpoint solo indica si la conexión auth está viva y cuándo fue el último pull con éxito.
Flujo típico
1) UI: el usuario pulsa "Conectar Google" → redirect del navegador → Google Consent → Callback
→ Rankion guarda el refresh token en BD
2) API: GET /google/connections # muestra: connection existe, scopes ok
3) API: GET /google/gsc/properties # lista lo que el usuario ha autorizado en GSC
4) API: POST /gsc/properties/{p}/link # vincula property a proyecto
5) API: POST /gsc/properties/{p}/sync # sync inicial (1 crédito)
6) API: GET /gsc/properties/{p}/metrics # los datos están listos
Notas
- OAuth solo por UI. Google no entrega refresh tokens de offline access para flows puramente API sin pasar por la consent screen. Inclúyelo en tu wizard de onboarding.
- URL-encode los property identifiers. Si no,
sc-domain:se interpreta como un scheme part desconocido (400). - Sync es async-light.
/syncarranca un job que corre 30 s – 5 min según el volumen de los 16 meses.last_synced_aten/connectionsmuestra el último run con éxito. - Las cuotas siguen aplicando. Rankion respeta la cuota GSC API (1200 queries/min/proyecto) — al superarla, error de rate limit con header
Retry-After. - DELETE de la connection revoca limpio. El refresh token se revoca en Google; un re-link accidental requiere pasar de nuevo por el consent flow.
Relacionado: Rank Tracking · API de Review Sources · Google Integrations.