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
| Service | Méthode | HTTP | Portée (min.) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| URL Inspection | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sites | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sites | add / delete | PUT / 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,
siteUrletfeedpathdoivent ê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.listet utilisez unsiteUrlexactement tel que retourné. UnsiteUnverifiedUserne 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
pageouquery(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 regroupement/ filtrage par
- 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)
- Sondez d'abord la fraîcheur. Interrogez les ~10 derniers jours groupés par
dateuniquement — 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. - Interrogez un jour à la fois (
startDate == endDate), une fois par jour, pour chaquetypedont 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. - Parcourez les résultats :
rowLimitmax 25 000 (par défaut 1 000), incrémentezstartRowde 25 000 jusqu'à ce qu'une page renvoie moins de lignes que demandé ou 0 ligne. - 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
pageet/ouquerysupprime 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 dimensionspage/query. - Les totaux diffèrent selon l'agrégation :
byProperty(dédupliqué par propriété) vsbyPage(par URL canonique). Si vous regroupez ou filtrez parpage,byPropertyn'est pas autorisé — utilisezauto. - 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. positionest 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).searchTypeest l'alias obsolète.dimensionFilterGroups[].filters[]:{dimension, operator, expression}; opérateursequals(par défaut, sensible à la casse pour page/query),notEquals,contains,notContains,includingRegex,excludingRegex(RE2). Les groupes sont combinés par ET ; seulgroupType: "and"est pris en charge.dimensionFilterGroups[].filterLists[]: correspondance exacte à valeurs multiples pourcountry/device({"dimension":"country","expressions":["usa","can"]}). Impossible de filtrer la même dimension à la fois dansfiltersetfilterLists.aggregationType:auto(par défaut),byPage,byProperty(pas pourdiscover/googleNews),byNewsShowcasePanel.dataState:final(par défaut),all(inclut les données fraîches, pas encore finalisées),hourly_all(requis pour la dimensionhour; ~10 jours disponibles). La réponsemetadata.firstIncompleteDate/firstIncompleteHourindique où les chiffres peuvent encore changer.
Pièges
- L'apparence de recherche se fait en deux étapes : interrogez d'abord avec
searchAppearancecomme seule dimension pour lister les types, puis filtrezsearchAppearance equals <TYPE>et ajoutez les autres dimensions — une requête par type. brandedClassification(BRANDED/NON_BRANDED) :equalsuniquement ; ne peut pas être combiné avec un filtrequerydans 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
startRowhors 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. rowsest 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.
inspectionUrldoit être soussiteUrl.- 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,googleCanonicalvsuserCanonical,crawledAs. - Le signal en masse le plus utile est
googleCanonical != userCanonical(Google a choisi une canonique différente). mobileUsabilityResultest obsolète.ampResult/richResultsResultsont 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.
- Créez/choisissez un projet Google Cloud → activez l'API Google Search Console.
- 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.
- Utilisez une bibliothèque cliente (recommandé) — par ex. Python
google-api-python-clientavecbuild("searchconsole", "v1", credentials=creds), Nodegoogleapisavecgoogle.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ôme | Cause | Action |
|---|---|---|
401 authError / expired | jeton 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 accessNotConfigured | API non activée sur le projet | activez l'API Search Console |
403/429 rateLimitExceeded, userRateLimitExceeded | QPS/QPM | backoff exponentiel avec gigue |
403/429 quotaExceeded (Search Analytics) | quota de charge | attendez 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 / badRequest | mauvaise énum, ordre des dates, filters/filterLists mélangés sur la même dimension, byProperty avec page | corrigez la requête ; ne réessayez pas |
500 / 503 backendError | transitoire | backoff 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)