API d’inspection d’URL Search Console : automatiser un audit

L’API d’inspection d’URL de Google Search Console permet d’interroger automatiquement les informations que Google possède sur la version indexée d’une URL. Elle sert à auditer un échantillon, repérer des familles d’erreurs et alimenter une file de diagnostic. Elle ne fournit pas le test en direct disponible dans l’interface, ne soumet pas les pages à l’indexation et ne garantit pas qu’une URL sera indexée.

La méthode efficace n’est donc pas de lancer l’API sur tout le sitemap. Construisez un échantillon par modèles de pages et états éditoriaux, conservez la date d’inspection, normalisez quelques champs fiables, puis reliez chaque anomalie à une vérification HTTP, HTML ou Search Console. L’automatisation accélère le tri ; elle ne remplace pas l’analyse de la cause.

Réponse en bref

Pour automatiser un audit avec l’API Inspection d’URL Search Console :

1. utilisez une propriété Search Console vérifiée et l’autorisation OAuth en lecture seule ;
2. inventoriez les URL attendues depuis le sitemap et vos données de publication ;
3. créez un échantillon stratifié par modèle, ancienneté et niveau de risque ;
4. appelez index.inspect pour chaque URL avec la propriété exacte ;
5. stockez la réponse brute et une ligne normalisée datée ;
6. comparez URL inspectée, canonical déclarée par le site et canonical choisie par Google ;
7. classez les cas en conforme, découverte à attendre, anomalie technique ou revue manuelle ;
8. vérifiez la réponse HTTP et le HTML avant de conclure ;
9. corrigez la cause par famille de pages, puis réinspectez un nouvel échantillon ;
10. utilisez le sitemap pour la découverte et ne détournez pas l’Indexing API pour des articles.

La prochaine action est de sélectionner trois à cinq URL par modèle de page : une récente, une ancienne, une importante, une variante canonique et, si elle existe, une URL ayant déjà connu un incident. Ce petit échantillon apporte souvent plus d’information qu’une collecte massive sans hypothèse.

Comprendre ce que renvoie réellement l’API

La méthode officielle est un appel POST à urlInspection/index:inspect. Le corps indique l’URL à inspecter, l’URL de la propriété Search Console et, éventuellement, une langue. Le résultat peut contenir l’état d’indexation ainsi que des analyses complémentaires lorsque Google dispose de ces informations.

Le contrat minimal ressemble à ceci :

{
  "inspectionUrl": "https://www.example.com/guide/",
  "siteUrl": "sc-domain:example.com",
  "languageCode": "fr-FR"
}

La propriété peut être une propriété de domaine ou une propriété avec préfixe d’URL. Utilisez exactement la valeur à laquelle le compte autorisé a accès. Une URL hors de la propriété ne devient pas inspectable parce qu’elle apparaît dans votre base.

Selon la référence officielle, l’API décrit la version présente dans l’index de Google. Elle ne déclenche pas le test en direct de l’URL courante. Cette distinction explique un décalage fréquent : vous corrigez une canonical ce matin, le HTML public est déjà correct, mais la réponse d’inspection conserve encore l’état de la dernière exploration connue.

L’interface Search Console offre des actions supplémentaires, dont le test en direct et la demande d’indexation. Elles ne doivent pas être confondues avec l’appel API. Le résultat automatisé est une observation datée, pas un verdict intemporel sur la page.

Séparer quatre opérations souvent confondues

Opération	Question	Disponible par index.inspect ?
Inspection de l’index	Que connaît Google de la version indexée ?	Oui
Test en direct	Que voit maintenant le test de Google sur l’URL ?	Non
Demande d’indexation	Peut-on signaler une URL dans l’interface ?	Non
Notification Indexing API	Cette URL éligible a-t-elle changé ?	Non, autre API et usages limités

La documentation Google réserve actuellement l’Indexing API aux pages contenant JobPosting ou BroadcastEvent intégré dans un VideoObject. Un BlogPosting ordinaire n’est pas éligible. Un statut HTTP réussi sur cette API ne constituerait de toute façon pas une garantie d’exploration, d’indexation ou de classement.

Pour plusieurs articles ou pages classiques, maintenez un sitemap propre et des liens internes explorables. Une demande manuelle peut être pertinente pour quelques URL importantes, mais Google recommande le sitemap pour un grand nombre d’URL. L’audit doit vérifier la découvrabilité au lieu de présenter une soumission comme une indexation forcée.

Préparer l’accès sans élargir les permissions

L’API utilise OAuth 2.0. Pour un audit qui ne modifie rien, demandez le périmètre en lecture seule documenté par Google. Le compte doit déjà disposer de l’accès à la propriété Search Console. Le script n’a besoin ni du mot de passe du compte ni d’un jeton copié dans le code.

Séparez trois composants :

• la configuration publique, comme la propriété et la langue ;
• le mécanisme d’autorisation géré hors du dépôt ;
• la collecte et la normalisation, qui ne reçoivent qu’un client authentifié.

Ne consignez jamais le jeton OAuth dans un fichier de résultats, un journal, un notebook partagé ou un message d’erreur. Limitez aussi les personnes pouvant lire les exports : les URL peuvent révéler des pages non destinées à être largement diffusées, des paramètres ou des chemins métiers.

Un pseudocode de collecte peut rester indépendant de la bibliothèque :

client = search_console_client(scope = "read_only")

for url in sample:
    result = client.inspect(
        inspection_url = url,
        site_url = configured_property,
        language = "fr-FR"
    )
    save_raw(url, inspected_at, result)
    save_normalized(normalize(url, inspected_at, result))

Prévoyez des reprises sur erreur et un débit inférieur aux quotas. Au 13 août 2026, Google documente pour l’inspection d’URL des limites par propriété de 2 000 requêtes par jour et 600 par minute, en plus de limites par projet. Ces chiffres peuvent évoluer. Le script doit traiter une réponse de quota comme un arrêt ou une reprise planifiée, jamais comme une permission de multiplier les identifiants.

Construire un échantillon stratifié

Inspecter uniquement la page d’accueil et les trois dernières publications crée un faux sentiment de couverture. À l’inverse, inspecter toutes les URL consomme le quota sans forcément produire une meilleure décision. Échantillonnez d’abord les familles qui partagent un gabarit ou un risque.

Une strate peut combiner :

• le modèle de page : article, offre, formation, catégorie, page locale ;
• l’ancienneté : moins de sept jours, récente, stable, ancienne ;
• la profondeur de clic depuis une page forte ;
• la présence dans le sitemap ;
• le statut éditorial attendu : indexable, canonique vers une autre page, exclu ;
• le type de rendu : HTML statique, serveur ou dépendant de JavaScript ;
• l’importance métier ;
• un historique de modification, migration ou anomalie.

Prenez quelques URL par strate. Ajoutez une sélection dirigée pour les pages stratégiques et une petite sélection aléatoire afin de détecter ce que vos hypothèses ne couvrent pas. Conservez la règle de sélection dans le rapport : sans elle, deux audits successifs peuvent sembler évoluer alors qu’ils n’ont pas observé le même périmètre.

Un plan raisonnable pour un site de contenu peut commencer par trente à cent URL. Le nombre exact dépend des modèles, de la taille et du risque, pas d’un seuil universel. Si un même défaut apparaît sur plusieurs URL d’un gabarit, interrompez la collecte exhaustive et examinez la cause commune.

Normaliser sans perdre la réponse brute

La réponse de l’API peut évoluer et comporter des structures optionnelles. Conservez un JSON brut horodaté pour l’audit, puis extrayez une table stable destinée au tri. N’interprétez pas l’absence d’un bloc optionnel comme une erreur automatique.

Une ligne normalisée utile contient :

Colonne	Usage
inspected_url	URL demandée à l’API
property	Propriété Search Console utilisée
inspected_at	Date et heure de la collecte
verdict	Verdict général rapporté
coverage_state	État de couverture rapporté
robots_state	État robots rapporté s’il existe
indexing_state	État d’indexation rapporté s’il existe
last_crawl_time	Dernière exploration connue s’il existe
page_fetch_state	Résultat de récupération rapporté
google_canonical	Canonical choisie par Google
user_canonical	Canonical déclarée par le site
crawled_as	Agent ou contexte d’exploration rapporté
referring_urls_count	Nombre de références éventuellement fournies
raw_result_path	Référence interne vers la réponse brute

Gardez la valeur d’origine et ne transformez pas trop tôt chaque champ en booléen. Les messages de couverture apportent un contexte, mais leur formulation peut varier. Une couche de normalisation doit être versionnée et testée avec des réponses contenant des champs absents.

Ajoutez des données issues de votre propre site : statut HTTP observé, canonical HTML actuelle, directive robots actuelle, présence sitemap et date de modification. C’est la comparaison entre état public et état indexé qui révèle le délai ou l’anomalie.

Comparer trois canonical au lieu de deux

Pour chaque URL, distinguez :

1. la canonical attendue selon votre registre éditorial ;
2. la canonical déclarée dans le HTML actuellement servi ;
3. la canonical choisie par Google dans la version indexée.

Si les trois correspondent, le cas est simple. Si le HTML diffère de l’attendu, corrigez le site. Si le HTML actuel est correct mais que Google conserve une ancienne canonical, regardez la date de dernière exploration et attendez une nouvelle observation avant de conclure. Si Google choisit durablement une autre URL, examinez les signaux contradictoires : doublons, redirections, liens internes, sitemap, contenu et cohérence des variantes.

L’article sur la canonicalisation d’une migration SEO et GEO détaille ce diagnostic. L’API fournit une pièce du dossier ; elle ne permet pas à elle seule d’expliquer pourquoi Google préfère une autre URL.

Transformer les résultats en file de diagnostic

Évitez un tableau rouge dès que le verdict n’est pas « PASS ». Classez chaque ligne selon l’action concrète et le niveau de preuve.

Conforme

L’URL indexable renvoie correctement, la canonical attendue et déclarée est cohérente, l’état de Google ne révèle pas d’anomalie nécessitant une action. Conservez la date de mesure et passez à la strate suivante.

Découverte ou réexploration à attendre

La page est récente ou vient d’être corrigée, elle est accessible, indexable, présente dans le sitemap et liée depuis une page explorée, mais l’état indexé n’a pas encore suivi. Notez la date, vérifiez le parcours de découverte et programmez une nouvelle inspection. Ne modifiez pas quotidiennement la page uniquement pour provoquer Google.

Anomalie technique reproductible

Le serveur renvoie un mauvais statut, la canonical actuelle est erronée, une directive bloque l’indexation, le contenu essentiel manque dans le HTML ou les liens ne sont pas explorables. Ouvrez un ticket sur le gabarit concerné avec URL, preuve HTTP, extrait HTML et réponse d’inspection datée.

Pour les pages qui reposent sur JavaScript, appliquez le protocole de rendu et d’indexation Google. L’état Search Console indique un résultat, tandis que la comparaison réponse HTTP, DOM navigateur, rendu et version indexée aide à isoler la phase défaillante.

Divergence de canonical ou doublon

Regroupez les URL qui convergent vers la même canonical Google. Cherchez un problème de variantes, paramètres, pagination, migration ou contenu trop proche. La correction se raisonne au niveau du cluster, pas URL par URL.

Revue manuelle

Placez ici les résultats incomplets, contradictoires ou difficiles à interpréter. Ouvrez l’interface Search Console pour les quelques cas qui nécessitent un test en direct ou davantage de détails. La file manuelle doit rester courte grâce au regroupement automatique.

Croiser l’inspection avec les données de performance

L’API d’inspection n’est pas l’API Search Analytics. Elle n’apporte ni clics, ni impressions, ni requêtes de performance. Une page peut être indexée sans recevoir d’impression, ou recevoir des impressions tout en présentant un état qui mérite une vérification.

Reliez les deux jeux avec prudence : URL normalisée, propriété, date et période. L’export Search Console vers BigQuery permet d’analyser les données de performance en masse, alors que l’inspection reste échantillonnée et orientée diagnostic.

Quelques croisements utiles :

• URL importante sans impression et état d’indexation incertain ;
• URL ayant perdu ses impressions après une migration ;
• modèle de page visible en performance mais canonical Google inattendue ;
• nouvelles pages présentes dans le sitemap sans observation indexée après une période à définir.

Ne déduisez pas une causalité d’une simple coïncidence de dates. Une baisse d’impressions peut venir de la demande, du classement, de la saison ou du périmètre de données. L’inspection aide à confirmer ou écarter une famille technique.

Automatiser la reprise sans créer une boucle agressive

Le collecteur doit être idempotent. Chaque tâche possède une clé composée au minimum de la propriété, de l’URL et de la campagne d’audit. En cas de coupure, il reprend les URL non terminées sans dupliquer les résultats validés.

Traitez séparément :

• les erreurs d’autorisation, qui arrêtent la campagne ;
• les URL hors propriété, qui sont des erreurs de préparation ;
• les erreurs temporaires, qui autorisent une reprise espacée ;
• les quotas, qui reportent le travail ;
• les réponses valides avec champs absents, qui restent des observations ;
• les URL redirigées, à comparer au registre attendu.

Ajoutez une temporisation progressive et une limite d’essais. Ne relancez pas immédiatement deux mille requêtes parce qu’une propriété ou un jeton est mal configuré. Un audit contrôlé doit protéger les quotas pour les usages importants de l’équipe.

L’API peut être intégrée à un workflow Python, mais le rapport final doit rester lisible sans le code. La page consultant SEO et GEO décrit comment replacer ce signal technique dans un audit plus large de visibilité et de contenu.

Recetter une correction par famille de pages

Après avoir corrigé une cause, vérifiez d’abord votre propre système :

1. réponse HTTP finale et chaîne de redirections ;
2. HTML brut et canonical ;
3. directives robots et en-têtes ;
4. présence dans le sitemap attendu ;
5. lien interne depuis une page pertinente ;
6. contenu principal dans le rendu ;
7. données structurées si elles sont nécessaires au modèle.

Inspectez ensuite quelques URL représentatives, pas toute la famille immédiatement. La version indexée peut conserver l’ancien état jusqu’à une nouvelle exploration. Enregistrez la date de correction, la date de dernière exploration rapportée et la date de réinspection. Ce calendrier empêche de rouvrir un bug simplement parce que Google n’a pas encore actualisé son observation.

Une fois le nouvel état visible sur l’échantillon, élargissez progressivement. Si le défaut persiste, revenez aux preuves et aux signaux contradictoires plutôt que de multiplier les demandes d’indexation.

Plan d’audit en une journée

Un premier audit borné peut suivre ce déroulé :

09 h 00 : cadrage

Listez les modèles de pages, les propriétés, les états attendus et les changements récents. Définissez les personnes autorisées à lire les résultats.

10 h 00 : échantillon

Sélectionnez les URL par strate, vérifiez qu’elles appartiennent à la propriété et figez la campagne. Conservez la justification de sélection.

11 h 00 : collecte

Lancez l’inspection avec un débit prudent. Stockez la réponse brute, les erreurs techniques et la table normalisée sans données d’autorisation.

13 h 30 : enrichissement local

Mesurez statut HTTP, canonical, robots, sitemap et liens internes. Identifiez les décalages entre page actuelle et version indexée.

15 h 00 : regroupement

Classez les cas par gabarit et cause probable. Ouvrez la revue manuelle uniquement pour les divergences qui ne peuvent pas être expliquées par les preuves locales.

16 h 30 : décision

Priorisez une ou deux corrections de système, définissez le nouvel échantillon et la date de réinspection. Le livrable est une file de diagnostic avec responsables et preuves, pas un export de centaines de lignes.

Limites

L’API Inspection d’URL reflète les informations de Google sur une version indexée et peut présenter des champs absents ou un état antérieur à la dernière correction du site. Elle ne fournit pas le test en direct, ne remplace pas l’interface pour certains diagnostics et ne garantit ni exploration, ni indexation, ni positionnement.

Les quotas, champs, libellés et mécanismes d’autorisation peuvent évoluer après le 13 août 2026. Vérifiez la documentation officielle avant d’exécuter une collecte. Respectez les accès à la propriété et la confidentialité des URL exportées. Pour un article ou une page classique, utilisez le sitemap et le maillage pour la découverte ; l’Indexing API n’est pas destinée aux BlogPosting.

Articles liés

• SEO JavaScript : tester rendu et indexation Google
• Canonicalisation d’une migration SEO et GEO
• Exporter Search Console dans BigQuery pour le SEO
• Consultant SEO et GEO