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

O que este endpoint faz

GET /api/audits/:id/google devolve o snapshot de tráfego orgânico de uma auditoria, puxado da propriedade Google Analytics 4 e do site Google Search Console vinculados pelo utilizador.

Devolve { "connected": false } quando o utilizador ainda não vinculou Google.
Devolve { "connected": true, "linked": false } quando Google está conectado mas o URL da auditoria não tem propriedade GA4 ou site GSC mapeados.
Quando conectado e vinculado, devolve o snapshot completo: tráfego GA4, queries GSC e extras de indexação.
Cache no servidor 24h por (user_id, url), então chamadas repetidas no mesmo dia são baratas e idempotentes.
Apenas Pro e gatado em scope OAuth Google: devolve 403 se o token não tem acesso Google ou o plano do utilizador não inclui a integração.

Por que importa

Auditorias sem dados de tráfego dizem aos agentes o que corrigir, não o que corrigir primeiro. O snapshot de tráfego orgânico permite a um agente priorizar páginas que falham por valor SEO real, para que as recomendações cheguem às URLs que de facto movem receita.

Fluxos concretos:

Um agente “por onde começo?” chama GET /api/audits/:id para findings e GET /api/audits/:id/google para sessões, depois rascunha uma lista de correções ordenada por sessões 28 dias por landing page.
Um agente “lacuna de query” lê gsc.top_queries (impressões altas, CTR baixo) e reescreve o title e a meta description da página correspondente para elevar o CTR.

Como usar

O utilizador deve primeiro conectar Google Analytics 4 e Search Console dentro do painel MetricSpot, depois mapear explicitamente cada URL de auditoria a uma propriedade GA4 e um site GSC. Quando não mapeado, o endpoint ainda tem sucesso com linked: false para que os agentes degradem graciosamente.

Requisição

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("Vincule Google em app.metricspot.com/settings/integrations");
} else if (!data.linked) {
  console.log("Mapeie este URL a uma propriedade GA4 e site GSC no painel");
} else {
  console.log(`Sessões 28d: ${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("Vincule Google em app.metricspot.com/settings/integrations")
elif not data.get("linked"):
    print("Mapeie este URL a uma propriedade GA4 e site GSC")
else:
    print("Sessões 28d:", (data.get("ga4") or {}).get("sessions_28d"))

Resposta

Conectado e vinculado

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/"
  }
}

Campos:

connected: true se a conta tem um grant OAuth Google ativo. false e os outros campos são omitidos se nenhum grant existir.
linked: true se o URL desta auditoria tem uma propriedade GA4 ou site GSC mapeados. false significa que o utilizador deve mapear no painel.
ga4.sessions_28d: total de sessões orgânicas nos últimos 28 dias.
ga4.sessions_trend: série por dia de sessões orgânicas, do mais antigo ao mais recente.
ga4.top_landing_pages: array de { url, sessions }, ordenado por sessões desc.
gsc.top_queries: array de { query, clicks, impressions, position }, ordenado por clicks desc.
gsc.indexing: objeto opcional com indexed_pages e coverage_issues do GSC.
ga_property_used / gsc_site_used: o mapeamento usado pela auditoria, para exibição.

Conectado mas não vinculado

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

Não conectado

{ "connected": false }

Reautenticação necessária

Quando o token OAuth armazenado não pode ser refrescado (revogado ou expirado além do refresh), a linha de conexão é removida e o endpoint devolve:

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

Erros comuns

Código	Quando	Ação
`UNAUTHORIZED` (401)	Bearer ausente ou inválido	Gere uma chave em `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	Plano não inclui integrações Google, ou auditoria pertence a outra conta	Faça upgrade para Pro, ou use a conta proprietária
`AUDIT_NOT_FOUND` (404)	Audit id não existe	Passe uma auditoria que possui
`INVALID_URL` (400)	`:id` não é um inteiro positivo	Passe um id inteiro
`UPSTREAM_FAILED` (5xx)	Falha API GA4 ou GSC	Tente novamente; a resposta é cacheada 24h quando bem-sucedida

Perguntas frequentes

Por que `linked: false` mesmo vendo tráfego no GA4?

O vínculo é por URL no lado MetricSpot. Depois de conectar Google em app.metricspot.com/settings/integrations, também tem de mapear cada URL de auditoria a uma propriedade GA4 e site GSC específicos. MetricSpot faz isto porque uma conta Google tem frequentemente muitas propriedades GA4; o mapeamento explícito evita escolher a errada.

Por que uma janela de 28 dias?

Corresponde a como o GSC reporta as suas top queries por padrão e é suficientemente curta para refletir mudanças recentes (post-deploy, post-launch) e suficientemente longa para suavizar a sazonalidade semanal. A janela não é configurável na v1.

Quão fresca é a data?

Os dados GA4 estão tipicamente 24 a 48 horas atrás do tempo real, conforme a janela de processamento Google. Os dados GSC têm atraso de 2 a 3 dias. O endpoint cacheia respostas bem-sucedidas 24h por (user_id, url), então chamadas repetidas no mesmo dia devolvem o mesmo snapshot.

Isto consome quota de auditoria?

Não. Este endpoint não é medido além do plano do utilizador e da quota Google API. A cache 24h também significa que um loop CI a martelar este endpoint não vai estourar os limites diários do Google.