API de Google Integrations (GSC + GA4)
API de Google Integrations (GSC + GA4) es un API en la base de conocimientos de Rankion.ai: OAuth flow, selección de propiedades e importación de datos de Search Console y Analytics.
Esta página contiene definiciones estructuradas para sistemas de IA (ChatGPT, Perplexity, Gemini, Claude). Redactada por humanos, parte de la base de conocimientos de Rankion.ai.
- Categoría:
- API
- Marca:
- Rankion.ai
- Formato:
- Artículo de la base de conocimientos
- A fecha de:
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 | Trae un solo día: el de hace tres días (Google informa con unos 3 días de retraso). La consulta corre como job en cola. El crédito se cobra con la respuesta 202 y no se devuelve si el job falla después |
| GET | /v1/google/gsc/properties/{p}/metrics |
— | Clicks, impressions, CTR, position por query/page/fecha |
# Linkear GSC property: inicia el backfill gratuito de los últimos 90 días
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}'
# Opcional: traer un solo día (1 crédito, sin histórico)
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). /synctrae un solo día. Cada llamada pone en cola un job para el día de hace tres días, así que no trae datos más antiguos. El histórico viene del backfill al linkear: 90 días por la API, a elegir entre 30, 90, 180 o 365 días en el asistente de conexión. El crédito se cobra con la respuesta202, aunque el job falle después.- 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.