API Google Search Console

Interagissez avec l'API Google Search Console (searchconsole v1 / webmasters v3) — analyses de recherche, inspection d'URL, plans de site et propriétés — tout en respectant ses quotas. Utilisez cette compétence pour « extraire des données Search Console », « exporter des données de performance GSC », « interroger les clics/impressions/CTR/position par page ou requête », « créer un pipeline ou un tableau de bord GSC », « obtenir plus de 1 000 / 25 000 lignes », « inspecter des URL / vérifier l'état d'indexation via l'API », « inspection d'URL en masse », « soumettre un plan de site via l'API », « lister les propriétés Search Console », configurer OAuth ou un compte de service pour Search Console, ou déboguer les erreurs « quota dépassé », 403 ou « L'utilisateur ne dispose pas d'autorisations suffisantes » de l'API Search Console.

Qu'est-ce que API Google Search Console ?

Cette compétence fournit une intégration complète et structurée avec l'API Google Search Console, couvrant ses quatre services principaux : les analyses de recherche (Search Analytics), l'inspection d'URL, les plans de site (Sitemaps) et la gestion des propriétés (Sites). Son principal atout est de guider l'utilisateur pour obtenir des données complètes et correctes tout en respectant strictement les quotas (QPM, QPD et charge), qui sont la principale source d'erreurs. Elle détaille le modèle de requête recommandé, les limites de données (50 000 lignes par jour par type de recherche), les règles de pagination et les maths des métriques (CTR pondéré, position pondérée). Elle prend également en charge la configuration de l'authentification via OAuth 2.0 (client installé ou compte de service), la gestion des erreurs avec des actions correctives, et l'optimisation des performances (gzip, réponses partielles, lot HTTP).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more Recherche et analyse de données skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait API Google Search Console ?

L'API Search Console permet un accès programmatique à la plupart des fonctionnalités de Google Search Console : le rapport Performances (Search Analytics), l'inspection d'URL, les plans de site et la liste des propriétés (Sites). C'est une API REST/JSON. Chaque appel nécessite OAuth 2.0 et un utilisateur (ou un compte de service) disposant d'une autorisation sur la propriété dans Search Console.

La partie difficile n'est pas d'effectuer un appel. C'est d'obtenir des données complètes et correctes sans dépasser le quota. L'essentiel de cette compétence porte là-dessus.

Quand utiliser cette compétence

  • Extraction de données de performances (clics, impressions, CTR, position) pour analyse, tableaux de bord, entrepôt de données ou investigations SEO.
  • Vérification de l'état d'indexation, de la canonique, de l'état robots/noindex ou de la validité des résultats enrichis pour des URL à grande échelle.
  • Lister les propriétés et les autorisations, lister ou soumettre des plans de site.
  • Concevoir un travail de synchronisation planifié, ou en réparer un qui atteint quotaExceeded, manque des lignes ou renvoie des chiffres qui ne correspondent pas à l'interface utilisateur.

Non couvert par cette API : le rapport d'indexation (couverture) des pages, les liens, les Core Web Vitals, les statistiques d'exploration, les actions manuelles, les suppressions et le bouton « Demander l'indexation ». Pour les Core Web Vitals sur le terrain, utilisez l'API CrUX ; pour les données de performances brutes en masse sur de grands sites, utilisez l'export de données en masse vers BigQuery de Search Console ; l'API d'indexation distincte ne prend en charge que les pages JobPosting / BroadcastEvent.

Les quatre services

ServiceMéthodeHTTPPortée (min.)
Search Analyticssearchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
URL InspectionurlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
Sitemapslist / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
Sitemapssubmit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
Siteslist / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
Sitesadd / deletePUT / DELETE /webmasters/v3/sites/{siteUrl}webmasters

URL racine : https://searchconsole.googleapis.com/ (document de découverte actuel, service searchconsole v1). Les anciens chemins https://www.googleapis.com/webmasters/v3/... apparaissent encore dans la documentation de Google et fonctionnent toujours pour les ressources webmasters/v3.

Portées : https://www.googleapis.com/auth/webmasters.readonly (lecture seule) et https://www.googleapis.com/auth/webmasters (lecture/écriture). Demandez lecture seule sauf si la tâche implique vraiment la soumission/suppression de plans de site ou l'ajout/suppression de sites.

Identifiants de propriété (siteUrl) — la source n°1 des erreurs 403/404

  • Propriété de domaine : sc-domain:example.com
  • Propriété de préfixe d'URL : https://www.example.com/ — le schéma, l'hôte et la barre oblique finale doivent correspondre exactement à ce qui se trouve dans Search Console.
  • Dans les chemins, siteUrl et feedpath doivent être complètement encodés en URL (https%3A%2F%2Fwww.example.com%2F, sc-domain%3Aexample.com). Les bibliothèques clientes le font pour vous ; HTTP brut ne le fait pas.
  • Commencez toujours par appeler sites.list et utilisez un siteUrl exactement tel que retourné. Un siteUnverifiedUser ne peut pas lire les données.

Quotas — lisez avant d'écrire une boucle

Détails complets et une feuille de calcul budgétaire : references/LIMITS.md.

Search Analytics

  • Limites QPM : 1 200 QPM par site, 1 200 QPM par utilisateur, 40 000 QPM et 30 000 000 QPD par projet. Exemple : un utilisateur interrogeant 3 sites obtient 1 200 QPM combinés ; deux utilisateurs sur un seul site partagent 1 200 QPM.
  • Quota de charge (celui qui mord vraiment) : coût interne d'une requête, suivi dans des fenêtres de 10 minutes (court terme) et 1 jour (long terme). Le coût augmente avec :
    • le regroupement/ filtrage par page ou query (les deux ensemble sont les plus coûteux),
    • la longueur de la plage de dates (6 mois ≫ 1 jour),
    • la réinterrogation de données déjà possédées.
  • Le dépassement de l'un de ces seuils renvoie la même erreur quotaExceeded. Court terme : attendez 15 minutes et réessayez. Si une seule requête dans une fenêtre de 10 minutes échoue encore, vous avez dépassé le quota de charge à long terme (quotidien) — réduisez le coût ; réessayer n'aidera pas avant demain.

Inspection d'URL : 2 000 QPD et 600 QPM par site ; 10 000 000 QPD et 15 000 QPM par projet. 2 000 par jour par propriété est le plafond réel — prévoyez un échantillonnage, ne prévoyez pas « inspecter chaque URL ».

Tout le reste (sites, plans de site) : 20 QPS et 200 QPM par utilisateur ; 100 000 000 QPD par projet.

Le traitement par lots n'économise pas le quota : un lot de n appels compte comme n requêtes. Le regroupement n'économise que la surcharge HTTP. Utilisation actuelle : console Google Cloud → APIs et services → API Search Console → Quotas.

Search Analytics : obtenir des données complètes et correctes

Schéma complet de requête/réponse et recettes : references/SEARCH-ANALYTICS.md.

Le modèle recommandé (d'après le guide « toutes vos données » de Google)

  1. Sondez d'abord la fraîcheur. Interrogez les ~10 derniers jours groupés par date uniquement — aucun filtre, aucune autre dimension. Les jours sans données sont simplement absents. Les données finales ont généralement 2 à 3 jours de retard.
  2. Interrogez un jour à la fois (startDate == endDate), une fois par jour, pour chaque type dont vous avez besoin. Une requête quotidienne d'un jour ne devrait pas dépasser votre quota quotidien ; une plage de 16 mois groupée par page+requête le fera.
  3. Parcourez les résultats : rowLimit max 25 000 (par défaut 1 000), incrémentez startRow de 25 000 jusqu'à ce qu'une page renvoie moins de lignes que demandé ou 0 ligne.
  4. Ne réextrayez jamais l'historique finalisé. Stockez-le ; ne récupérez que les nouveaux jours (et récupérez les jours non finalisés récents si vous utilisez dataState: "all").
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
{
  "startDate": "2026-11-14",
  "endDate":   "2026-11-14",
  "dimensions": ["page", "query", "country", "device"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Limites de données strictes que vous devez expliquer aux parties prenantes

  • L'API renvoie les premières lignes, pas toutes les lignes : au maximum 50 000 lignes par jour par type de recherche (triées par clics), quel que soit le parcours.
  • Le regroupement/ filtrage par page et/ou query supprime certaines données (pour maintenir le calcul borné) et les requêtes rares anonymisées ne sont jamais renvoyées. Donc la somme des lignes < total de la propriété. Pour des totaux précis, interrogez sans les dimensions page/query.
  • Les totaux diffèrent selon l'agrégation : byProperty (dédupliqué par propriété) vs byPage (par URL canonique). Si vous regroupez ou filtrez par page, byProperty n'est pas autorisé — utilisez auto.
  • Les dates sont en heure du Pacifique (America/Los_Angeles), pas UTC.
  • La conservation des données de performances dans Search Console est d'environ 16 mois. Persistez-les si vous avez besoin d'un historique plus long.

Calculs corrects des métriques

  • CTR d'un groupe = sum(clics) / sum(impressions). Ne faites jamais la moyenne des CTR.
  • Position d'un groupe = pondérée par les impressions : sum(position × impressions) / sum(impressions). Ne faites jamais la moyenne des positions.
  • position est la position moyenne supérieure basée sur 1 ; plus elle est basse, mieux c'est.

Champs clés de la requête (référence rapide)

  • dimensions : date, hour, query, page, country (ISO 3166-1 alpha-3, en minuscules dans les résultats, ex. usa), device (DESKTOP/MOBILE/TABLET), searchAppearance, brandedClassification.
  • type : web (par défaut), image, video, news (onglet Actualités), googleNews (news.google.com + app), discover, webMultimodal (Lens / Recherche par cercle / chargements d'images). searchType est l'alias obsolète.
  • dimensionFilterGroups[].filters[] : {dimension, operator, expression} ; opérateurs equals (par défaut, sensible à la casse pour page/query), notEquals, contains, notContains, includingRegex, excludingRegex (RE2). Les groupes sont combinés par ET ; seul groupType: "and" est pris en charge.
  • dimensionFilterGroups[].filterLists[] : correspondance exacte à valeurs multiples pour country / device ({"dimension":"country","expressions":["usa","can"]}). Impossible de filtrer la même dimension à la fois dans filters et filterLists.
  • aggregationType : auto (par défaut), byPage, byProperty (pas pour discover/googleNews), byNewsShowcasePanel.
  • dataState : final (par défaut), all (inclut les données fraîches, pas encore finalisées), hourly_all (requis pour la dimension hour ; ~10 jours disponibles). La réponse metadata.firstIncompleteDate / firstIncompleteHour indique où les chiffres peuvent encore changer.

Pièges

  • L'apparence de recherche se fait en deux étapes : interrogez d'abord avec searchAppearance comme seule dimension pour lister les types, puis filtrez searchAppearance equals <TYPE> et ajoutez les autres dimensions — une requête par type.
  • brandedClassification (BRANDED / NON_BRANDED) : equals uniquement ; ne peut pas être combiné avec un filtre query dans la même requête ; données à partir du 2026-02-21 et uniquement pour les propriétés de premier niveau avec suffisamment de volume.
  • Les résultats sont triés par clics décroissants, sauf lorsqu'ils sont groupés par date (date croissante). Les égalités sont arbitraires — ne vous fiez pas à l'ordre pour la déduplication.
  • Un startRow hors limites renvoie 200 avec zéro ligne, pas une erreur. Les données exactement sur une limite de 25 000 renvoient une page suivante vide.
  • rows est absent (pas []) lorsqu'il n'y a pas de données.

Inspection d'URL

Schéma complet, énumérations et tableau de triage : references/URL-INSPECTION.md.

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.example.com/page", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }
  • Signale la version indexée uniquement. Il ne peut pas tester une URL en direct, et ne peut pas demander l'indexation.
  • inspectionUrl doit être sous siteUrl.
  • Lisez indexStatusResult : verdict (PASS = valide, NEUTRAL = exclu, FAIL = erreur), coverageState (la chaîne lisible par l'homme, ex. « Soumise et indexée »), robotsTxtState, indexingState, pageFetchState, lastCrawlTime, googleCanonical vs userCanonical, crawledAs.
  • Le signal en masse le plus utile est googleCanonical != userCanonical (Google a choisi une canonique différente).
  • mobileUsabilityResult est obsolète. ampResult / richResultsResult sont absents lorsqu'ils ne s'appliquent pas.
  • Budget : 2 000/jour/propriété. Priorisez un échantillon : premières pages par clics, modèles récemment modifiés, une URL par modèle/motif, URL de nouveaux plans de site.

Sites et plans de site

Voir references/SITES-AND-SITEMAPS.md. sites.list → siteEntry[] {siteUrl, permissionLevel} avec siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser. sitemaps.list → sitemap[] avec path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted (contents[].indexed est obsolète — ne le signalez pas). submit / delete ne prennent pas de corps et nécessitent la portée lecture/écriture. Ce sont des écritures. Confirmez avec l'utilisateur avant de les appeler.

Authentification et configuration

Étape par étape, ainsi que les lignes d'installation de la bibliothèque pour chaque langage : references/AUTH-AND-SETUP.md.

  1. Créez/choisissez un projet Google Cloud → activez l'API Google Search Console.
  2. Choisissez un justificatif :
    • Client OAuth installé/bureau : pour un humain exécutant des scripts localement ; l'utilisateur consent dans un navigateur et vous stockez le jeton d'actualisation.
    • Compte de service : pour des tâches sans surveillance. Ensuite, ajoutez l'e-mail du compte de service en tant qu'utilisateur sur la propriété dans Search Console (Paramètres → Utilisateurs et autorisations). Le statut Restreint suffit pour les lectures ; Propriétaire/Complet est nécessaire pour les écritures. Sans cette étape, chaque appel renvoie 403.
    • Les clés API ne sont pas acceptées pour ces ressources ; OAuth 2.0 est le seul protocole pris en charge.
  3. Utilisez une bibliothèque cliente (recommandé) — par ex. Python google-api-python-client avec build("searchconsole", "v1", credentials=creds), Node googleapis avec google.searchconsole("v1").
from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)

resp = gsc.searchanalytics().query(siteUrl="sc-domain:example.com", body={
    "startDate": "2026-11-14", "endDate": "2026-11-14",
    "dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", [])   # absent quand vide

Ne jamais imprimer, journaliser ou valider des jetons, secrets client ou clés de compte de service.

Erreurs et nouvelles tentatives

Carte complète : references/ERRORS.md.

SymptômeCauseAction
401 authError / expiredjeton invalide/expiréactualisez le jeton ; vérifiez les portées
403 insufficientPermissions / "L'utilisateur ne dispose pas d'autorisations suffisantes pour le site"mauvaise forme de siteUrl, ou le principal n'est pas un utilisateur de la propriétésites.list, utilisez le siteUrl exact ; ajoutez le compte de service dans Search Console
403 accessNotConfiguredAPI non activée sur le projetactivez l'API Search Console
403/429 rateLimitExceeded, userRateLimitExceededQPS/QPMbackoff exponentiel avec gigue
403/429 quotaExceeded (Search Analytics)quota de chargeattendez 15 min une fois ; si une seule requête échoue encore → charge à long terme : réduisez la plage de dates ou abandonnez page/query, reprenez demain
400 invalidParameter / badRequestmauvaise énum, ordre des dates, filters/filterLists mélangés sur la même dimension, byProperty avec pagecorrigez la requête ; ne réessayez pas
500 / 503 backendErrortransitoirebackoff et réessayez (borné)

Performances

references/BATCH-AND-PERFORMANCE.md : gzip (Accept-Encoding: gzip et un User-Agent contenant gzip), réponses partielles via fields= (ex. fields=rows(keys,clicks,impressions)), et lot HTTP (multipart/mixed, ≤ 1 000 appels, exécutés dans n'importe quel ordre, chaque appel compte toujours dans le quota).

Le script d'assistance

scripts/gsc.py est un utilitaire CLI monofichier utilisant uniquement la bibliothèque standard Python 3.9+. Il écrit la progression sur stderr et les données sur stdout (JSONL par défaut, ou CSV/JSON). Il pagine, esp

... (tronqué pour la traduction)

Skills associés