Guide : Search Console API

How to pull and manage Recherche Google Console données with code — the Search Analytics, Inspection d’URL, Sitemaps, and Sites APIs, OAuth, quotas, and quand to utiliser BigQuery à la place.

Première publication : 23 juin 2026 · Dernière mise à jour : 3 août 2026 · Advanced
Langues

Pour website properties, the Recherche Google Console API exposes Search Analytics, Inspection d’URL, Sitemaps, and Sites resources via OAuth 2,0. Search Analytics renvoie up to 25 000 top rows per requête; Inspection d’URL is capped at 2 000 requêtes/day and 600/minute per property. Search Console now aussi has Instagram, TikTok, X, and YouTube platform properties, but Google's current platform documentation ne fait pas specify legacy API identifiers or endpoint prise en charge, so ce guide ne fait pas claim API compatibility pour les.

TL;DR — The Search Console API is four REST APIs sous webmaster-tools/v1 — Search Analytics, Inspection d’URL, Sitemaps, Sites — tout OAuth 2,0, tout scoped to verified properties seulement. Search Analytics renvoie 1–25 000 rows per requête (par défaut 1 000) but “ne fait pas guarantee to retourner tout données rows but plutôt top ones,” so pour completeness at scale vous graduate to the BigQuery bulk données export. Inspection d’URL is hard-capped at 2 000 QPD / 600 QPM per site — que arithmetic is ce que gates large-scale index monitoring.

Evidence for this claim The Search Console API exposes Search Analytics, Sitemaps, Sites, and URL Inspection operations. Scope: Current Search Console API surface. Confidence: high · Verified: Google Developers: Search Console API Evidence for this claim Search Analytics results are bounded by API quotas and may omit some rows; the API does not guarantee every data row. Scope: Current Search Analytics query behavior and quotas. Confidence: high · Verified: Search Console API: Search Analytics query

Ce API guide is scoped to website properties. Ne faites pas assume le sites, Search Analytics, Inspection d’URL, or Sitemaps endpoints prise en charge Instagram, TikTok, X, or YouTube platform properties jusqu’à Google documents the identifier and endpoint contract.

The four APIs En un coup d’œil

Google’s propre framing of ce que the API fait: it lets vous “view, ajouter, or supprimer properties and sitemaps, run avancé requêtes pour Recherche Google results données pour the properties que vous manage in Search Console, and tester individual pages.” Que maps cleanly onto the four resources, tout sous webmaster-tools/v1:

  • Search Analytics API — the Performances report, programmatically: clicks, impressions, CTR, position by dimension (requête, page, country, device, search appearance, date, hour).
  • Inspection d’URL API — the index status of a unique URL, the programmatic sibling of the Inspection d’URL outil.
  • Sitemaps API — liste, obtenir, submit, and delete sitemaps.
  • Sites API — liste, ajouter, and supprimer verified properties.
Evidence for this claim The Search Console API exposes Search Analytics, Sitemaps, Sites, and URL Inspection operations. Scope: Current Search Console API surface. Confidence: high · Verified: Google Developers: Search Console API

It exposes beaucoup of ce que vous déjà utiliser in the interface — the Performances report and the Inspection d’URL outil — as endpoints vous pouvez script contre. It isn’t a 1:1 mirror, though: the API doesn’t guarantee complet UI parity (URL Inspection’s live tester, pour instance, is UI-only — voir ci-dessous), and neither API accès nor automation on its propre guarantees indexation, rankings, trafic diagnosis, or AI-search visibility.

Auth: OAuth 2,0, two scopes, verified properties seulement

There’s aucun API clé. Every appel is OAuth 2,0 — Google is explicit que “tout requêtes to the Recherche Google Console API doit be authorized by an authenticated utilisateur.” Vous register an app in Google Cloud, requête a scope, and obtenir a short-lived accès token. Two scopes exist:

  • https://www.googleapis.com/auth/webmasters — lire/écrire.
  • https://www.googleapis.com/auth/webmasters.readonly — read-only.

Pour server-to-server automation (a nightly reporting job, an index monitor) vous grant a service account accès to the property and skip the interactive consent flow.

Pour website properties, two property-identifier formats matter ici aussi: une URL-prefix property is réussi as a complet property URL (Google’s propre exemple is http://www.example.com/), and a Domain property uses the sc-domain:example.com formulaire — vous have to réussir whichever formulaire matches how the property is verified in Search Console. Soit façon, the service account (or utilisateur) nécessite to be granted accès to que exact property; it’s pas a bypass pour ownership or a blanket grant à travers every property on the account.

And the gate que trips everyone up: “Vous doit have appropriate accès (owner, complet, lire) to quelconque Recherche Google Console account que vous wish to accès en utilisant the API.” Appel the API pour a property you’re pas verified on and it renvoie nothing — pas an error you’ll necessarily notice, simplement vide données.

Search Analytics API — the Performances report, at scale

Commencer with the ceiling, pas the convenience: Google’s propre caveat is que “The API is bounded by internal limitations of Search Console and ne fait pas guarantee to retourner tout données rows but plutôt top ones.” Pagination extends how far vous pouvez page into que top-rows liste — it doesn’t supprimer the ceiling. Quand vous besoin every row, that’s the cue to reach pour BigQuery bulk export (ci-dessous), pas a bigger rowLimit.

Dans que ceiling, ce is encore the un la plupart personnes come pour. The raison it beats the interface is the rowLimit parameter: “[Optional; Valid range is 1–25 000; Par défaut is 1 000].” The interface export caps near 1 000 rows; the API donne vous up to 25 000 per requête, and vous paginate past que with startRow. On a site with a long tail of requêtes, that’s the difference entre seeing the top of votre données and seeing plus of it — encore pas tout of it.

Two plus choses shape ce que comes back. Premier, dataState contrôle freshness: final (the par défaut) renvoie seulement finalized données, all inclut fresh, recently collected données, and hourly_all donne hourly breakdowns que are explicitly partial — la réponse metadata flags a first_incomplete_date or first_incomplete_hour, and Google notes valeurs après que point peut encore modifier. Second, Search Analytics quotas aren’t a unique number: the usage limites page splits les into charger limites (a resource-based allowance mesuré in 10-minute and 1-day chunks — wider date ranges, plus dimensions, and heavier filtering tout draw it bas faster) and the QPS/QPM/QPD request-rate limites covered ci-dessous. Vous pouvez hit the charger ceiling avant vous hit la requête-rate ceiling.

Inspection d’URL API — and the quota que en réalité constrains vous

The Inspection d’URL API “view[s] the indexé, or indexable, status of the provided URL. Presently seulement the status of the version in the Google index is disponible; vous pouveznot tester the indexability of a live URL.” Que dernier clause is a réel scope limite, pas a technicality: the interface’s Inspection d’URL outil peut run a live tester contre lune page as it exists correct now; the API peut seulement report on the version Google déjà has indexé. Utiliser the API to construire index-coverage monitoring à travers nombreux URLs — pas as a substitute pour the UI’s live tester.

Here’s où the math matters. Per site, vous obtenir 2 000 requêtes per day and 600 per minute. (Per project the ceiling is far plus élevé — 10 000 000/day and 15 000/minute — but the per-site cap is ce que bites.) Si vous vouloir to monitor the index status of a 50 000-URL site, vous pouvez’t inspect les tout in a day; vous batch and schedule à travers days, or vous prioritize. Few posts do ce arithmetic, and it’s the unique biggest planning constraint on large-scale index monitoring.

By contrast, Search Analytics is generous — 1 200 QPM per site and per utilisateur — and the autre resources (Sitemaps, Sites) sit at 20 QPS / 200 QPM per utilisateur. URL Inspection is the tight un.

Sitemaps and Sites APIs

The Sitemaps API is the management couche pour votre sitemaps: it “submits a sitemap pour a site,” “deletes a sitemap from ce site,” “retrieves information à propos de a spécifique sitemap,” and “listes le sitemaps-entries submitted pour ce site, or inclus in le sitemap index fichier.” Le sitemap resource it renvoie inclut fields comme path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors, and a contents array — handy pour auditing sitemap health at scale.

The Sites API listes, adds, and removes verified properties — utile si vous manage nombreux properties and vouloir to provision or audit les programmatically.

Quand to utiliser BigQuery bulk export à la place

Pour grand sites, the API’s 25 000-rows-per-request, top-rows-only model becomes a ceiling. Google’s réponse isn’t a fifth API resource que renvoie the même shape of données — it’s a separate, scheduled export pipeline: the bulk données export to BigQuery. Think of the choice as pull vs. scheduled push, pas “API A vs. API B.” Google’s own framing: “Schedule a daily export of votre Search Console performances données to BigQuery, où vous pouvez run complex requêtes over votre données or export it to an external storage service. En utilisant the bulk données export fonctionnalité, you’ll voir tout the performances données disponible to Search Console pour votre property, with the exception of anonymized requêtes.”

That’s the decision rule:

  • Interface export — ~1 000 rows, rapide one-off regarder.
  • Search Analytics API — up to 25 000 rows/requête, paginate, scriptable; great pour moderate on-demand pulls and dashboards.
  • BigQuery bulk export — tout disponible performances données, daily, aucun row cap; the correct outil une fois you’ve got tens of thousands of pages or requêtes.

The un chose none of les give vous is anonymized requêtes — the terms Google hides pour privacy. That’s a réel gap, pas a bug vous pouvez fonctionner autour. I know the scale of it firsthand: as Ahrefs’ Brand Ambassador I helped surface a study où we pulled tout the données disponible from the API à travers a very grand sample of sites and trouvé Google hides the keyword term on a grand share of clicks. We plus tard construit que into Ahrefs Rank Tracker — complet history of votre GSC données, the percent of clicks going to anonymized requêtes, and a custom CTR curve construit from votre propre numbers. Quand someone indique vous the API renvoie “all your data,” que anonymized slice is the honest asterisk.

Courant utiliser cas

  • Automated reporting — scheduled pulls into Sheets or a warehouse.
  • BI dashboards — Looker Studio or BigQuery on top of the Performances données.
  • Large-scale index/coverage monitoring — Inspection d’URL, batched dans the 2 000/day quota.
  • CTR curve building — model attendu CTR by position from votre propre données.
  • Anomaly alerting — flag click/impression drops automatically.

Ce is aussi how third-party outils fonctionner: quand Ahrefs or a Looker Studio connector “integrates Search Console,” they’re appel ces même APIs (and increasingly, the BigQuery export) on votre behalf.

Add an expert note

Pin an expert quote

New person? Create their unclaimed profile at /admin/experts/ → Pin a quote first.