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

Ce que fait cet endpoint

GET /api/audits/:id/google renvoie le snapshot de trafic organique d’un audit, tiré de la propriété Google Analytics 4 et du site Google Search Console liés.

Renvoie { "connected": false } quand l’utilisateur n’a pas encore lié Google.
Renvoie { "connected": true, "linked": false } quand Google est connecté mais que l’URL de l’audit n’a pas de propriété GA4 ou de site GSC mappés.
Une fois connecté et lié, renvoie le snapshot complet : trafic GA4, queries GSC et extras d’indexation.
Cache côté serveur 24h par (user_id, url) : les appels répétés dans la journée sont peu coûteux et idempotents.
Réservé à Pro et gaté sur le scope OAuth Google : renvoie 403 si le token n’a pas l’accès Google ou si le plan de l’utilisateur n’inclut pas l’intégration.

Pourquoi c’est important

Les audits sans données de trafic disent aux agents quoi corriger, pas par quoi commencer. Le snapshot de trafic organique permet à un agent de prioriser les pages qui échouent par la valeur SEO réelle, pour que les recommandations atterrissent sur les URL qui font du chiffre.

Workflows concrets :

Un agent “par où commencer ?” appelle GET /api/audits/:id pour les findings et GET /api/audits/:id/google pour les sessions, puis rédige une liste de corrections ordonnée par sessions 28 jours.
Un agent “écart de requête” lit gsc.top_queries (impressions hautes, CTR bas) et réécrit le title et la meta description de la page pour faire monter le CTR.

Comment l’utiliser

L’utilisateur doit d’abord connecter Google Analytics 4 et Search Console dans le tableau de bord MetricSpot, puis mapper explicitement chaque URL d’audit à une propriété GA4 et un site GSC. Quand pas mappé, l’endpoint réussit avec linked: false pour que les agents dégradent proprement.

Requête

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("Liez Google sur app.metricspot.com/settings/integrations");
} else if (!data.linked) {
  console.log("Mappez cette URL à une propriété GA4 et un site GSC dans le tableau de bord");
} else {
  console.log(`Sessions 28j : ${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("Liez Google sur app.metricspot.com/settings/integrations")
elif not data.get("linked"):
    print("Mappez cette URL à une propriété GA4 et un site GSC")
else:
    print("Sessions 28j :", (data.get("ga4") or {}).get("sessions_28d"))

Réponse

Connecté et lié

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

Champs :

connected : true si le compte a un grant OAuth Google actif. false et les autres champs sont omis si aucun grant n’existe.
linked : true si l’URL de cet audit a une propriété GA4 ou un site GSC mappés. false signifie que l’utilisateur doit la mapper dans le tableau de bord.
ga4.sessions_28d : total des sessions organiques sur les 28 derniers jours.
ga4.sessions_trend : série par jour des sessions organiques, du plus ancien au plus récent.
ga4.top_landing_pages : tableau de { url, sessions }, trié par sessions décroissantes.
gsc.top_queries : tableau de { query, clicks, impressions, position }, trié par clics décroissants.
gsc.indexing : objet optionnel avec indexed_pages et coverage_issues depuis GSC.
ga_property_used / gsc_site_used : le mapping utilisé par l’audit, pour affichage.

Connecté mais pas lié

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

Pas connecté

{ "connected": false }

Réauthentification requise

Quand le token OAuth stocké ne peut pas être rafraîchi (révoqué ou expiré au-delà du refresh), la ligne de connexion est supprimée et l’endpoint renvoie :

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

Erreurs courantes

Code	Quand	Action
`UNAUTHORIZED` (401)	Bearer manquant ou invalide	Créez une clé sur `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	Plan sans intégration Google, ou audit appartenant à un autre compte	Passez à Pro, ou utilisez le compte propriétaire
`AUDIT_NOT_FOUND` (404)	Audit id inexistant	Passez un audit que vous possédez
`INVALID_URL` (400)	`:id` n’est pas un entier positif	Passez un id entier
`UPSTREAM_FAILED` (5xx)	Panne API GA4 ou GSC	Réessayez ; la réponse est cachée 24h une fois OK

Questions fréquentes

Pourquoi `linked: false` alors que je vois du trafic dans GA4 ?

Le lien est par URL côté MetricSpot. Après avoir connecté Google sur app.metricspot.com/settings/integrations, vous devez aussi mapper chaque URL d’audit à une propriété GA4 et un site GSC précis. MetricSpot fait cela parce qu’un même compte Google a souvent plusieurs propriétés GA4 ; le mapping explicite évite de prendre la mauvaise.

Pourquoi une fenêtre de 28 jours ?

C’est la fenêtre par défaut de GSC pour les top queries, assez courte pour refléter les changements récents (post-deploy, post-launch) et assez longue pour lisser la saisonnalité hebdomadaire. La fenêtre n’est pas configurable en v1.

À quel point les données sont-elles fraîches ?

GA4 a un retard typique de 24 à 48 heures par rapport au temps réel, selon la fenêtre de traitement de Google. GSC a un retard de 2 à 3 jours. L’endpoint cache les réponses réussies 24h par (user_id, url) : les appels répétés dans la même journée renvoient le même snapshot.

Cela consomme-t-il du quota d’audit ?

Non. Cet endpoint n’est pas compté au-delà du plan utilisateur et du quota Google. Le cache 24h fait aussi qu’une boucle CI qui martèle l’endpoint ne va pas exploser la limite quotidienne Google.