AI SEO In Detail › Module A · Les fondations › Épisode 4
API Google Search Console : récupérez vos propres données
Utilisez l'API Google Search Console pour extraire toutes les requêtes et pages de votre site, au-delà des limites de l'interface, avec un compte de service et un kit Python gratuit.
La lecture de la vidéo la charge depuis YouTube (mode privacy-enhanced). La vidéo est en anglais, avec des sous-titres dans votre langue.
Script d'extraction quotidienne Search Console + schéma SQLite
gsc_pull.py + schema.sql : extrayez chaque ligne de vos données Google Search Console via l'API, jour par jour, dans SQLite. Compte de service via une variable d'environnement, trois extractions par jour, pagination complète au-delà de 25 000 lignes, cache JSON brut et upsert qui ne double jamais un jour.
- Créer un compte de service — Activez l'API Search Console dans un projet Google Cloud, téléchargez la clé JSON du compte de service dans votre dossier personnel, puis ajoutez son adresse comme utilisateur avec accès restreint sur votre propriété.
- Indiquer la clé au script — Définissez GSC_KEY_FILE avec le chemin de la clé et GSC_SITE avec votre propriété. Lancez le selftest, puis l'extraction : date, date + page et date + page + requête, chaque ligne, mise en cache et insérée en upsert.
- Vérifier une fois, puis planifier — Comparez une journée complète avec l'interface grâce à la commande check, puis exécutez-la chaque jour : re-extrayez les cinq derniers jours pour que les chiffres récents se stabilisent et que l'historique continue de grandir.
Python 3.9+ · SQLite · aucune clé incluse · sans inscription
Les fichiers sont en anglais.
1,150 mots · traduction de la narration de l’épisode.
Introduction
Le bouton d'export de Search Console donne mille lignes. Avec plus de requêtes, le reste n'est tout simplement pas dans le fichier.
Et Search Console ne garde qu'environ seize mois d'historique. Tout ce qui est plus ancien disparaît, sauf si vous l'avez sauvegardé.
Les deux problèmes ont la même solution : récupérer les données vous-même, via l'API, chaque jour, dans votre propre base. Dans cet épisode, on fait exactement ça pour l'un de mes propres sites. On configure l'accès avec un compte de service, on écrit la requête, on pagine toutes les lignes et on les stocke pour ne jamais perdre l'historique.
Accès : un compte de service

Pour appeler l'API depuis un script, il faut une identité qui n'est pas vous. C'est un compte de service : un utilisateur robot dans Google Cloud.
Trois étapes. Créez un projet Google Cloud et activez-y la Search Console API. Créez un compte de service et téléchargez sa clé, un fichier JSON. Puis, dans Search Console, ouvrez les paramètres utilisateurs de la propriété, et ajoutez l'adresse e-mail du compte de service comme utilisateur.
Quelle autorisation ? Restreint suffit pour lire les données. Donnez-lui l'accès minimal qui fonctionne. Et utilisez le scope lecture seule, pour qu'un bug ne puisse rien modifier.
Où mettre la clé ? Même règle qu'à l'épisode précédent. Hors du dossier du projet, lisible par vous seul. Je garde une clé dans mon dossier personnel, et le script y accède via une variable d'environnement.
Un compte peut être ajouté à plusieurs propriétés. J'ai un compte de service pour tous mes sites : un seul script récupère tout.
La requête : dimensions et filtres

La méthode que vous utiliserez pour presque tout s'appelle search analytics query. Vous lui donnez une plage de dates, des dimensions et, en option, des filtres.
Les dimensions définissent le découpage des données. Date, page, query, country, device et search appearance. Vous choisissez la combinaison et obtenez une ligne par combinaison, avec clics, impressions, CTR et position.
Voici la première surprise. Les dimensions choisies changent les totaux. Si vous demandez seulement la date, Google compte par site, et vous obtenez le total complet. Ajoutez la dimension page, et il compte par page. Ajoutez aussi query, et des lignes sont supprimées pour la confidentialité.
Voici une journée sur l'un de mes sites. D'abord, une précision : les données sont réelles, issues de la Search Console API, mais anonymisées. Le domaine, les URL des pages et les termes de recherche sont remplacés, pour rester sur les principes et pas sur les mots-clés. Les chiffres sont intacts.
L'extraction par date seule indique trois cent cinquante clics ce jour-là. Additionnez les lignes query et page du même jour : environ soixante. Même site, même jour. Ce n'est pas un bug de votre script. L'épisode neuf explique tout cela.
Ma règle pratique : stocker deux extractions séparées. Une par date et page, qui donne les totaux complets par page. Et une par date, page et query, pour le détail.
Limites de lignes et pagination
Chaque appel renvoie au plus vingt-cinq mille lignes. S'il y en a plus, vous redemandez avec un décalage startRow, vingt-cinq mille, puis cinquante mille, et ainsi de suite jusqu'à un appel vide.
Voici ce que ça donne sur mon site, six jours d'affilée.
Chaque barre est une journée de lignes query et page. La ligne est la limite d'export de mille lignes. Chaque jour : entre environ quatre mille sept cents et six mille deux cents lignes. Soit cinq à six fois la limite. Tout ce qui dépasse la ligne, l'export ne vous l'aurait jamais montré.
Récupérez un jour à la fois. Chaque appel reste petit, et la tâche quotidienne est simple : une date en entrée, toutes les lignes en sortie.
Même avec la pagination, l'API ne donne pas toutes les requêtes. Les requêtes très rares et celles jugées privées par Google sont exclues. À l'épisode neuf, vous verrez combien cela pèse sur ce même site.
Délai des données et données récentes

Les données Search Console ne sont pas en temps réel. Les deux ou trois derniers jours manquent souvent ou sont incomplets. L'API peut renvoyer des données plus fraîches et provisoires sur demande, mais ces chiffres peuvent encore changer.
Pour le stockage quotidien, je fais donc deux choses. Je récupère une date de quelques jours en arrière, une fois définitive. Et au passage suivant, je récupère à nouveau les derniers jours et les écrase. Ne prenez jamais les chiffres d'hier dans Search Console pour définitifs.
Pour comparer des périodes, ne comparez que des jours complets. Une semaine qui finit hier ressemblera toujours à une baisse.
Stocker les extractions quotidiennes

Maintenant, on stocke. J'utilise SQLite : un fichier, pas de serveur, et assez rapide pour des millions de lignes. On installe l'espace de travail complet à l'épisode six.
Deux tables, une par extraction. Une ligne par date et page. Une ligne par date, page et query. La date et les autres dimensions forment la clé, donc si vous récupérez deux fois le même jour, la nouvelle ligne remplace l'ancienne au lieu de la doubler.
Sauvegardez aussi la réponse brute en JSON, comme avec DFS. Cette fois, les données sont gratuites, mais le cache vous protège toujours des bugs de parsing.
Puis planifiez. Une tâche quotidienne récupère les cinq derniers jours en upsert. Après un an de fonctionnement, vous aurez un historique que Search Console ne montre plus.
Pièges à éviter
Trois pièges fréquents.
Type de propriété. Une propriété de domaine couvre sous-domaines et protocoles. Une propriété préfixe d'URL ne couvre que ce préfixe. Vérifiez que le script interroge la propriété que vous voyez dans l'interface.
La position est une moyenne, et les moyennes cachent beaucoup. L'épisode huit explique comment bien la lire.
Et n'utilisez pas le rapport sitemaps de l'API pour juger l'indexation. Son chiffre « indexed » s'est révélé peu fiable dans mes mesures. Pour le statut d'indexation, utilisez URL Inspection, sur lequel on reviendra à l'épisode dix-sept.
Contrôles de cohérence sur la première extraction
Avant de bâtir quoi que ce soit, vérifiez une fois les données dans l'interface. Choisissez un jour complet. Voici cette vérification sur mon propre site.
L'extraction par date seule doit égaler le total de l'interface ce jour-là, ou s'en approcher. Idem pour la somme de l'extraction par page. Sinon, vous interrogez sans doute une autre propriété, un autre type de recherche, ou un jour pas encore définitif.
L'extraction par query sera plus basse. Ici, environ soixante clics sur trois cent cinquante. Pas de panique face à cet écart. Ce sont les requêtes masquées dont on vient de parler.
Puis vérifiez le nombre de lignes par jour, comme dans le graphique précédent. Un jour soudain avec bien moins de lignes, alors que les clics sont normaux, signale souvent un bug de pagination, pas un événement SEO. Dix minutes de vérification évitent un graphique faux pendant un an.
Pour conclure
Un compte de service, deux extractions par jour, la pagination, et une base de données qui garde votre historique. Le script et le schéma sont en description. Prochain épisode : réunir Analytics, Search Console et DFS en un modèle de données. À bientôt.