Google Search Console API : comment automatiser son reporting SEO ?

Pour automatiser un reporting SEO avec l’API Google Search Console, on interroge chaque jour la méthode searchanalytics.query sur une journée de données, avec les dimensions utiles (date, requête, page, pays, appareil), on pagine par blocs de 25 000 lignes, puis on stocke le résultat dans une base ou un tableur qui alimente le tableau de bord. L’accès passe par OAuth 2.0, le plus souvent avec un compte de service ajouté à la propriété.

À quoi sert l’API Search Console par rapport à l’interface ?

L’API ne contient pas de données « en plus » : elle donne accès aux mêmes mesures que le rapport Performances (clics, impressions, CTR, position moyenne), avec davantage de lignes et sans action manuelle. Sa valeur tient à l’automatisation et au stockage.

Pour un diagnostic ponctuel, comme une chute des clics dans Search Console, l’interface reste plus rapide. L’API devient rentable dès qu’une analyse doit être répétée chaque semaine ou portée sur des milliers de pages.

Anatomie d’une requête searchAnalytics.query

La requête est un POST vers https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query, où siteUrl est encodé : sc-domain:exemple.fr pour une propriété de domaine, https://www.exemple.fr/ pour une propriété préfixe d’URL. Le corps JSON accepte les paramètres suivants, tels que décrits dans la documentation de référence.

Les dimensions, une par une

• query : la requête saisie. Les requêtes anonymisées par Google pour protéger la vie privée n’apparaissent pas en ligne, même si elles comptent dans les totaux.
• page : l’URL canonique affichée dans le résultat. Croisée avec query, c’est la vue la plus utile pour détecter une cannibalisation entre pages, mais aussi la plus coûteuse.
• country : code pays ISO 3166-1 alpha-3 (fra, bel, che).
• device : DESKTOP, MOBILE ou TABLET.
• date : indispensable pour historiser ; les jours sans données sont omis.
• hour : vue horaire des données fraîches, à combiner avec dataState: hourly_all.
• searchAppearance : type d’apparence dans les résultats ; Google recommande de l’interroger seul pour lister les valeurs, puis de filtrer dessus.

Agrégation par page ou par propriété

Avec byProperty, une recherche où deux de vos pages apparaissent compte une impression pour le site ; avec byPage, chaque page compte la sienne. Les totaux diffèrent donc légitimement. Lorsqu’on regroupe ou filtre par page, l’agrégation se fait par page. Choisissez un mode et ne mélangez jamais deux modes dans une même série historique.

Authentification et propriété : donner accès sans exposer de secret

1. Projet Google Cloud : activez la Google Search Console API dans un projet dédié au reporting.
2. Compte de service : créez-le pour une collecte serveur sans interaction. Sa clé JSON est un secret : stockez-la hors du répertoire public, jamais dans un dépôt de code, et limitez les droits du fichier.
3. Accès à la propriété : dans Search Console, Paramètres › Utilisateurs et autorisations, ajoutez l’adresse e-mail du compte de service avec un accès restreint, suffisant pour la lecture.
4. Portée OAuth : demandez https://www.googleapis.com/auth/webmasters.readonly. La portée en écriture n’est utile que pour gérer sitemaps ou propriétés.
5. Alternative sans serveur : un script Google Apps Script lié à un Google Sheets peut s’authentifier avec le compte de l’utilisateur, à condition de déclarer les portées dans le manifeste.

Générateur de requête Search Console API

Choisissez la période, les dimensions, les filtres, le type de recherche et la limite. L’outil affiche la configuration en langage clair, le payload JSON prêt à envoyer, un exemple d’appel et les alertes de cohérence (dimension horaire sans hourly_all, plage supérieure à seize mois, limite hors bornes…). Il fonctionne entièrement dans le navigateur.

Exemples de requêtes : PHP, Python et Apps Script

Exemple 1 : payload quotidien par page et par requête

{
  "startDate": "2026-10-15",
  "endDate": "2026-10-15",
  "dimensions": ["date", "page", "query"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Exemple 2 : pages d’un répertoire sur mobile en France

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["page"],
  "dimensionFilterGroups": [{
    "groupType": "and",
    "filters": [
      {"dimension": "page", "operator": "includingRegex", "expression": "^https://www\\.exemple\\.fr/blog/"},
      {"dimension": "country", "operator": "equals", "expression": "fra"},
      {"dimension": "device", "operator": "equals", "expression": "MOBILE"}
    ]
  }],
  "rowLimit": 5000
}

Exemple 3 : PHP avec la bibliothèque cliente Google

Le site Devsource et une grande partie des sites vitrines tournent en PHP : la bibliothèque officielle google/apiclient, installée avec Composer, gère l’authentification du compte de service.

<?php
require __DIR__ . '/vendor/autoload.php';

$client = new Google\Client();
// Fichier hors du répertoire public, lisible uniquement par le serveur.
$client->setAuthConfig('/chemin/prive/gsc-service-account.json');
$client->addScope(Google\Service\SearchConsole::WEBMASTERS_READONLY);
$service = new Google\Service\SearchConsole($client);

$day = (new DateTimeImmutable('-3 days'))->format('Y-m-d');
$request = new Google\Service\SearchConsole\SearchAnalyticsQueryRequest();
$request->setStartDate($day);
$request->setEndDate($day);
$request->setDimensions(['date', 'page', 'query']);
$request->setRowLimit(25000);

$startRow = 0;
do {
    $request->setStartRow($startRow);
    $rows = $service->searchanalytics->query('sc-domain:exemple.fr', $request)->getRows() ?? [];
    foreach ($rows as $row) {
        [$date, $page, $query] = $row->getKeys();
        // Insérer $date, $page, $query, $row->getClicks(), $row->getImpressions(),
        // $row->getCtr(), $row->getPosition() dans la table historisée.
    }
    $startRow += 25000;
} while (count($rows) === 25000);

Exemple 4 : Python pour une base de données

from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
creds = service_account.Credentials.from_service_account_file(
    "/chemin/prive/gsc-service-account.json", scopes=SCOPES)
service = build("searchconsole", "v1", credentials=creds)

def fetch_day(site, day, search_type="web"):
    rows, start = [], 0
    while True:
        body = {"startDate": day, "endDate": day, "type": search_type,
                "dimensions": ["date", "page", "query"],
                "rowLimit": 25000, "startRow": start}
        batch = service.searchanalytics().query(siteUrl=site, body=body).execute().get("rows", [])
        rows.extend(batch)
        if len(batch) < 25000:
            return rows
        start += 25000

Exemple 5 : Google Sheets avec Apps Script

Dans le manifeste appsscript.json, déclarez les portées https://www.googleapis.com/auth/webmasters.readonly, https://www.googleapis.com/auth/script.external_request et https://www.googleapis.com/auth/spreadsheets.currentonly, puis :

function importSearchConsole() {
  const site = encodeURIComponent('sc-domain:exemple.fr');
  const day = Utilities.formatDate(new Date(Date.now() - 3 * 864e5), 'America/Los_Angeles', 'yyyy-MM-dd');
  const response = UrlFetchApp.fetch(
    'https://www.googleapis.com/webmasters/v3/sites/' + site + '/searchAnalytics/query', {
      method: 'post',
      contentType: 'application/json',
      headers: { Authorization: 'Bearer ' + ScriptApp.getOAuthToken() },
      payload: JSON.stringify({ startDate: day, endDate: day, dimensions: ['page'], rowLimit: 5000 }),
      muteHttpExceptions: true
    });
  if (response.getResponseCode() !== 200) throw new Error(response.getContentText());
  const rows = (JSON.parse(response.getContentText()).rows || [])
    .map(r => [day, r.keys[0], r.clicks, r.impressions, r.ctr, r.position]);
  if (rows.length) SpreadsheetApp.getActive().getSheetByName('GSC')
    .getRange(SpreadsheetApp.getActive().getSheetByName('GSC').getLastRow() + 1, 1, rows.length, 6).setValues(rows);
}

Un déclencheur temporel quotidien suffit. Au-delà de quelques dizaines de milliers de lignes par jour, un tableur atteint ses limites : passez à une base de données.

Limites, quotas et écarts avec l’interface

Trois écarts avec l’interface sont normaux : les requêtes anonymisées (présentes dans les totaux, absentes des lignes), la différence entre agrégation par page et par propriété, et la coupure due aux limites de lignes. Pour vérifier votre chaîne, comparez le total d’une requête sans dimension (ou avec la seule dimension date) au graphique de l’interface : ils doivent concorder.

Automatiser le reporting : collecte, stockage et tableau de bord

Choisir la destination

Le schéma de table minimal

CREATE TABLE gsc_daily (
  day          DATE         NOT NULL,
  search_type  VARCHAR(12)  NOT NULL,
  page         VARCHAR(2048) NOT NULL,
  query        VARCHAR(512) NOT NULL,
  country      CHAR(3)      NULL,
  device       VARCHAR(8)   NULL,
  clicks       INT          NOT NULL,
  impressions  INT          NOT NULL,
  ctr          DECIMAL(7,6) NOT NULL,
  position     DECIMAL(7,2) NOT NULL,
  collected_at DATETIME     NOT NULL
);

Stockez les lignes brutes, puis calculez les vues dans le tableau de bord. Ne stockez pas un CTR ou une position « moyenne de moyennes » : recalculez-les à partir des clics, impressions et positions pondérées par les impressions.

Fréquence et rattrapage

• Quotidien : collectez la journée J-3 en final. Relancez le même jour quelques jours plus tard si vous utilisez all, car les données récentes peuvent évoluer.
• Rattrapage initial : bouclez jour par jour sur les seize mois disponibles, en espaçant les appels.
• Idempotence : une clé unique (jour, type, page, requête, pays, appareil) évite les doublons en cas de relance.

Comparer des périodes sans se tromper

Comparez des périodes de même longueur et de même composition hebdomadaire (28 jours contre les 28 précédents, ou contre la même période un an plus tôt pour neutraliser la saisonnalité). Segmentez ensuite par répertoire, appareil et pays : c’est ce découpage qui permet de distinguer un trafic en baisse malgré des positions stables d’une vraie perte de visibilité. Les mêmes séries servent à mesurer l’effet d’une mise à jour d’ancien article ou d’une migration de site.

Les erreurs courantes et leur correction

Conclusion : un reporting fiable commence par une collecte modeste et régulière

L’API Search Console ne rend pas le SEO plus visible : elle rend sa mesure plus complète, plus ancienne et plus facile à croiser. Le bon point de départ tient en quatre décisions : une propriété et un compte de service correctement autorisés, une requête quotidienne d’une journée, un stockage brut historisé et des comparaisons calculées en aval.

Ces données alimentent ensuite le diagnostic : analyser une chute brutale de trafic SEO, suivre les positions par groupe de requêtes ou relier les clics Google au trafic venant des assistants IA dans GA4. Si vous préférez déléguer la chaîne de collecte, notre équipe d’automatisation IA et data met en place des flux sécurisés, et notre accompagnement SEO transforme ces séries en priorités. En cas de baisse déjà constatée, l’audit de chute de trafic SEO part directement de ces exports.