Search Analytics est souvent la première API que l’on veut brancher quand une équipe SEO veut suivre ses requêtes, ses pages, ses clics, ses impressions, son CTR et sa position moyenne. Le piège, c’est de croire que l’API Google Search Console donne un export complet et neutre de toute la Search Console. Elle donne surtout un signal de performance à interpréter avec ses dimensions, ses filtres et ses limites.
Ce guide sert à cadrer l’usage de searchAnalytics.query sans inventer de donnée. Si le besoin est déjà de construire une matrice SEO, une watchlist, un dashboard ou un système d’alertes, la page API SEO et Analytics reste l’owner business. L’article explique le mécanisme; la landing sert à cadrer le projet.
Quand passer du guide au projet API SEO ?
Si vous devez historiser les positions, comparer 24h / 7j / 28j, relier les pages à des landings propriétaires ou éviter la cannibalisation blog/landing, le sujet dépasse l’export GSC. Il faut cadrer la donnée, le stockage, les seuils et les décisions.
Endpoint officiel searchAnalytics.query
La documentation Google confirme que Search Analytics: query s’appelle en POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query. Le paramètre siteUrl correspond à la propriété Search Console, par exemple une URL-prefix ou une propriété domaine de type sc-domain:example.com.
L’appel nécessite une autorisation Google avec un scope adapté, notamment https://www.googleapis.com/auth/webmasters.readonly pour lire les données. Cette permission n’est pas un détail: elle décide qui peut extraire les données SEO, sur quelle propriété et avec quel niveau de responsabilité.
La réponse regroupe les lignes selon les dimensions demandées et renvoie les métriques clicks, impressions, ctr et position. Ces métriques n’ont de valeur que si le périmètre est stable: même propriété, même période, même type de recherche, mêmes filtres et même logique d’agrégation.
Dimensions, filtres et métriques à cadrer
Les dimensions structurantes sont query, page, country, device, searchAppearance, date et hour. Google permet aussi de filtrer sans forcément grouper par la même dimension, ce qui est puissant mais dangereux si l’équipe ne documente pas exactement ce qu’elle compare.
Exemple: une matrice query + page aide à repérer la page qui répond réellement à une intention. Une matrice page + device montre si le mobile dégrade le CTR. Un groupement par date permet de suivre la tendance, mais il ne doit pas être mélangé à une lecture ponctuelle sans garder la même fenêtre de calcul.
Les filtres officiels acceptent des opérateurs comme equals, contains, notContains, notEquals, includingRegex ou excludingRegex. En production, le filtre doit être traité comme un contrat: une regex trop large peut masquer une baisse, une page canonicalisée différemment peut disparaître, et une requête exacte peut ignorer des variantes utiles.
Limites, fraîcheur et lignes manquantes
Google précise que l’API est bornée par les limites internes de Search Console et ne garantit pas de retourner toutes les lignes, mais plutôt les principales. C’est central pour un dashboard: une absence de ligne n’est pas toujours une absence de requête. Elle peut aussi refléter un seuil, un tri ou un volume trop faible.
Le paramètre rowLimit accepte officiellement de 1 à 25 000 lignes, avec 1 000 par défaut, et startRow permet de paginer par offset. Cela ne transforme pas l’API en export exhaustif. Pour des longues traînes, il faut souvent multiplier les vues, filtrer par page, par dossier ou par famille de requêtes, puis conserver la méthode d’extraction dans la documentation.
Le paramètre dataState permet de demander des données fraîches ou horaires, mais les données récentes peuvent être incomplètes. Google renvoie alors des métadonnées comme first_incomplete_date ou first_incomplete_hour. Une alerte 24h doit donc être lue comme un signal chaud, pas comme un verdict définitif.
Exemple de requête simplifiée
L’exemple ci-dessous est volontairement simplifié et basé sur la structure officielle. Il ne doit pas être copié tel quel sans adapter la propriété, les dates, les droits OAuth et le stockage côté projet.
{
"startDate": "2026-06-01",
"endDate": "2026-06-23",
"dimensions": ["query", "page"],
"type": "web",
"dimensionFilterGroups": [
{
"groupType": "and",
"filters": [
{
"dimension": "page",
"operator": "contains",
"expression": "/integration-api/"
}
]
}
],
"rowLimit": 25000,
"startRow": 0,
"dataState": "final"
}Ce payload répond à une question précise: quelles requêtes et quelles pages touchent le dossier /integration-api/ sur une période donnée. Pour un audit 24h, on peut grouper par hour, mais il faut alors accepter la nature partielle du signal et stocker les métadonnées d’incomplétude.
Use cases SEO actionnables
Le premier cas utile est la matrice requête/page/owner. On compare la page qui reçoit les impressions à la landing qui devrait posséder l’intention. Si un article blog domine une requête transactionnelle comme “intégrateur API”, le plan d’action n’est pas de pousser l’article plus fort, mais de transférer l’intention vers la landing.
Le deuxième cas est l’alerte CTR. Une requête positionnée entre 4 et 12 avec beaucoup d’impressions et peu de clics mérite une révision de title, meta, réponse courte ou maillage. Cette décision doit rester liée à la valeur business de la page, pas seulement au volume.
Le troisième cas est la watchlist d’opportunités. Les requêtes a_garder = oui sont historisées sur 7, 14 et 28 jours. Les requêtes hors fit restent en non pour éviter de produire du contenu parasite. C’est exactement l’usage de notre matrice SEO interne: choisir ce qu’on pousse, ce qu’on surveille et ce qu’on refuse.
Maillage et sortie business
Pour approfondir Google Search Console au sens large, l’article API Google Search Console : requêtes et indexation fiables couvre aussi URL Inspection, sitemaps et gouvernance des propriétés. Ici, l’angle reste volontairement centré sur Search Analytics.
Pour transformer ce cadrage en système exploitable, la sortie naturelle est la page API SEO et Analytics. Elle doit rester propriétaire des intentions business comme API SEO, dashboard SEO, matrice GSC, alertes positions et suivi de cannibalisation.
Le bon prochain pas consiste à définir la matrice: requête, page dominante, landing cible, position, clics, impressions, CTR, tendance, a_garder, action éditoriale et date de contrôle. Sans cette colonne de décision, l’API produit du bruit. Avec elle, elle devient un moteur de priorisation SEO.
