GET /api/audits/:id/google - Docs de MetricSpot

Què fa aquest endpoint

GET /api/audits/:id/google retorna la instantània de tràfic orgànic d’una auditoria, obtinguda de la propietat de Google Analytics 4 i del lloc de Google Search Console vinculats per l’usuari.

Retorna { "connected": false } quan l’usuari encara no ha vinculat Google.
Retorna { "connected": true, "linked": false } quan Google està connectat però la URL de l’auditoria no té cap propietat GA4 ni lloc GSC mapejat.
Quan està connectat i mapejat, retorna la instantània completa: tràfic GA4, queries de GSC i extres d’indexació.
Cache al servidor durant 24 hores per (user_id, url), de manera que les crides repetides dins del dia són econòmiques i idempotents.
Només per a Pro i restringit per scope OAuth de Google: retorna 403 si el token no té accés a Google o si el pla de l’usuari no inclou la integració.

Per què importa

Les auditories sense dades de tràfic diuen als agents què cal arreglar, però no què cal arreglar primer. La instantània de tràfic orgànic permet a un agent ordenar les pàgines amb errors per valor orgànic real perquè les recomanacions aterrin a URLs que realment mouen ingressos.

Fluxos concrets:

Un agent “per on començo?” crida GET /api/audits/:id per als findings i GET /api/audits/:id/google per a les sessions, i redacta una llista de correccions ordenada per sessions de 28 dies per landing page.
Un agent de buits de queries llegeix gsc.top_queries (impressions altes, CTR baix) i reescriu el title i la meta description de la pàgina coincident per pujar el CTR.

Com utilitzar-lo

L’usuari primer ha de connectar Google Analytics 4 i Search Console des del dashboard de MetricSpot, i després mapejar explícitament cada URL d’auditoria a una propietat GA4 i a un lloc GSC. Si no està mapejat, l’endpoint encara respon correctament amb linked: false perquè els agents puguin degradar sense problemes.

Petició

GET /api/audits/12345/google HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits/12345/google \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits/12345/google", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const data = await res.json();

if (!data.connected) {
  console.log("Link Google at app.metricspot.com/settings/integrations");
} else if (!data.linked) {
  console.log("Map this URL to a GA4 property and GSC site in the dashboard");
} else {
  console.log(`28d sessions: ${data.ga4?.sessions_28d}`);
  for (const q of data.gsc?.top_queries?.slice(0, 5) ?? []) {
    const ctr = q.impressions ? q.clicks / q.impressions : 0;
    console.log(`${q.query}: CTR ${(ctr * 100).toFixed(1)}%`);
  }
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits/12345/google",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
data = r.json()
if not data.get("connected"):
    print("Link Google at app.metricspot.com/settings/integrations")
elif not data.get("linked"):
    print("Map this URL to a GA4 property and GSC site")
else:
    print("Sessions 28d:", (data.get("ga4") or {}).get("sessions_28d"))

Resposta

Connectat i mapejat

200 OK:

{
  "connected": true,
  "linked": true,
  "ga4": {
    "sessions_28d": 14328,
    "sessions_trend": [
      { "date": "2026-04-16", "sessions": 482 },
      { "date": "2026-04-17", "sessions": 511 }
    ],
    "top_landing_pages": [
      { "url": "https://example.com/", "sessions": 5104 },
      { "url": "https://example.com/pricing", "sessions": 2871 }
    ]
  },
  "gsc": {
    "top_queries": [
      { "query": "example pricing", "clicks": 612, "impressions": 8412, "position": 4.2 },
      { "query": "example alternative", "clicks": 387, "impressions": 5101, "position": 7.8 }
    ],
    "indexing": {
      "indexed_pages": 184,
      "coverage_issues": 3
    }
  },
  "ga_property_used": {
    "property_id": "properties/123456789",
    "display_name": "Example - GA4"
  },
  "gsc_site_used": {
    "site_url": "https://example.com/"
  }
}

Camps:

connected: true si el compte té un grant OAuth de Google viu. false i la resta de camps s’ometen si no hi ha grant.
linked: true si la URL d’aquesta auditoria té una propietat GA4 o un lloc GSC mapejat. false vol dir que l’usuari ho ha de mapejar al dashboard.
ga4.sessions_28d: total de sessions orgàniques als darrers 28 dies.
ga4.sessions_trend: sèrie diària de sessions orgàniques, més antiga primer.
ga4.top_landing_pages: array de { url, sessions }, ordenat per sessions descendent.
gsc.top_queries: array de { query, clicks, impressions, position }, ordenat per clicks descendent.
gsc.indexing: objecte opcional amb indexed_pages i coverage_issues de GSC.
ga_property_used / gsc_site_used: el mapeig que ha utilitzat l’auditoria, per mostrar.

Connectat però no mapejat

{ "connected": true, "linked": false }

Sense connectar

{ "connected": false }

Cal reautenticar

Quan el token OAuth desat no es pot refrescar (revocat o expirat més enllà del refresh), la fila de connexió s’esborra i l’endpoint retorna:

{ "connected": false, "reason": "reauth_required" }

Errors habituals

Codi	Quan	Acció
`UNAUTHORIZED` (401)	Token Bearer absent o invàlid	Emet una clau a `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	El pla no inclou integracions de Google, o l’auditoria és d’un altre compte	Actualitza a Pro o utilitza el compte propietari
`AUDIT_NOT_FOUND` (404)	L’id d’auditoria no existeix	Passa una auditoria que sigui teva
`INVALID_URL` (400)	`:id` no és un enter positiu	Passa un id enter
`UPSTREAM_FAILED` (5xx)	Caiguda de l’API de GA4 o GSC	Reintenta; la resposta es cacheja 24h un cop té èxit

Preguntes freqüents

Per què `linked: false` si veig tràfic a GA4?

El vincle és per URL al costat de MetricSpot. Després de connectar Google a app.metricspot.com/settings/integrations, també has de mapejar cada URL d’auditoria a una propietat GA4 específica i a un lloc GSC. MetricSpot ho fa així perquè un compte de Google sovint té diverses propietats GA4; el mapeig explícit evita triar-ne una d’incorrecta.

Per què una finestra de 28 dies?

Coincideix amb com GSC reporta les seves top queries per defecte, i és prou curta per reflectir canvis recents (post-deploy, post-llançament) i prou llarga per suavitzar la estacionalitat setmanal. La finestra no és configurable a la v1.

Quina frescor té la dada?

Les dades de GA4 normalment van 24 a 48 hores per darrere del temps real, segons la finestra de processament de Google. Les dades de GSC tenen 2 a 3 dies de retard. L’endpoint cacheja respostes correctes durant 24 hores per (user_id, url), de manera que les crides repetides el mateix dia retornen la mateixa instantània.

Consumeix allocació d’auditoria?

No. Aquest endpoint no està comptabilitzat més enllà del pla de l’usuari i la quota de l’API de Google. La cache de 24 hores també implica que un bucle de CI martellejant aquest endpoint no es cruspirà els límits diaris de Google.