Hướng dẫn về Search Console API

TL;DR — Đó Search Console API cho phép bạn grab của bạn Google Search Console dữ liệu với code thay vì clicking qua đó interface. đây là cách bạn nhận hơn hơn đó UI hands bạn — đó export trong đó interface tops out khoảng 1 000 các hàng, trong khi đó API cho bạn lên để 25 000 theo yêu cầu. Bạn log trong với Google (OAuth, không một đơn giản API key), và bạn chỉ nhận dữ liệu cho các trang bạn đã verified.

Điều gì đó Search Console API là

Search Console cho thấy bạn cách trang web của bạn làm trong Google — điều gì các truy vấn bạn xếp hạng cho, cách nhiều clicks và impressions bạn nhận, liệu của bạn các trang là được lập chỉ mục. Đó API cho bạn programmatic access để nhiều of đó giống nhau dữ liệu và những giống nhau controls, so bạn có thể feed điều này vào một spreadsheet, một dashboard, hoặc một script đó chạy on một schedule. đây là không đầy đủ UI parity, though — vài điều (như trực tiếp-kiểm thử một URL) chỉ exist trong đó interface, và có API access hoặc automation không by itself bảo đảm lập chỉ mục, thứ hạng, traffic diagnosis, hoặc AI-khả năng hiển thị trên tìm kiếm.

Có four pieces:

1. Tìm kiếm Analytics API — của bạn Performance báo cáo numbers (clicks, impressions, CTR, average position), hỏng xuống by query, trang, country, device, và date.
2. URL Inspection API — đó chỉ mục status of một single URL. Điều này các báo cáo đó version hiện tại trong Google chỉ mục; đó interface URL Inspection tool có thể cũng chạy một trực tiếp kiểm thử, mà đó API không thể làm.
3. Sitemaps API — list, submit, hoặc delete của bạn sitemaps.
4. Các trang API — list, thêm, hoặc xóa đó properties on của bạn account.

Nền tảng-thuộc tính boundary: Search Console hiện tại có tách biệt Instagram, TikTok, X, và YouTube properties, nhưng Google hiện tại nền tảng tài liệu mô tả của họ interface các báo cáo và báo cáo export—không một siteUrl identifier hoặc hỗ trợ contract cho những legacy endpoints. Đó API workflow trong này bài viết do đó covers website properties chỉ. LinkedIn không phải một supported nền tảng thuộc tính.

Vì sao dùng điều này thay vì đó interface

Đó big một: các hàng. Nếu bạn export đó Performance báo cáo từ đó Tìm kiếm Console interface, bạn nhận khoảng 1 000 các hàng. Đó API trả về lên để 25 000 các hàng theo yêu cầu, và bạn có thể trang qua cho hơn. Nếu bạn đã nhận một site với thousands of các truy vấn hoặc các trang, đó interface đơn giản không cho thấy bạn hầu hết of của bạn dữ liệu.

Đó other reason là automation. Khi đây là an API call, bạn có thể chạy điều này mỗi morning, dump điều này vào một dashboard, hoặc alert yourself khi clicks drop.

Đó catch

Bạn có thể chỉ pull dữ liệu cho properties bạn đã verified trong Search Console. Point đó API tại một site bạn không own và bạn nhận không có gì lại — đó là đó hầu hết phổ biến beginner stumble.

Và đó API không cho bạn mọi thứ. Điều này trả về đó top các hàng, không đó đầy đủ list, và điều này không bao giờ cho thấy bạn đó các truy vấn Google anonymizes cho quyền riêng tư. Cho một big site đó wants đó hoàn tất picture, đó tốt hơn tool là đó bulk dữ liệu export to BigQuery — more on that in the Advanced version.

TL;DR — Đó Search Console API là four REST APIs dưới webmaster-tools/v1 — Tìm kiếm Analytics, URL Inspection, Sitemaps, Các trang — all OAuth 2,0, all scoped để verified properties chỉ. Tìm kiếm Analytics trả về 1–25 000 các hàng theo yêu cầu (default 1 000) nhưng “does not guarantee to return all data rows but rather top ones,” (bản dịch) «không bảo đảm để trả về all dữ liệu các hàng nhưng rather top ones,» so cho tính đầy đủ tại quy mô bạn graduate để đó BigQuery bulk dữ liệu export. URL Inspection là hard-capped tại 2 000 QPD / 600 QPM theo site — đó arithmetic là điều gì gates lớn-quy mô chỉ mục monitoring.

Này API hướng dẫn là scoped để website properties. Không assume đó Các trang, Tìm kiếm Analytics, URL Inspection, hoặc Sitemaps endpoints hỗ trợ Instagram, TikTok, X, hoặc YouTube nền tảng properties until Google documents đó identifier và endpoint contract.

Đó four APIs tại một glance

Google own cách diễn đạt of điều gì đó API làm: điều này cho phép bạn “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (bản dịch) «view, thêm, hoặc xóa properties và sitemaps, chạy advanced các truy vấn cho Google Search kết quả dữ liệu cho đó properties đó bạn manage trong Search Console, và kiểm thử riêng lẻ các trang.» Đó maps cleanly onto đó four các tài nguyên, all dưới webmaster-tools/v1:

• Tìm kiếm Analytics API — đó Performance báo cáo, programmatically: clicks, impressions, CTR, position by dimension (query, trang, country, device, tìm kiếm appearance, date, hour).
• URL Inspection API — đó chỉ mục status of một single URL, đó programmatic sibling of đó URL Inspection tool.
• Sitemaps API — list, nhận, submit, và delete sitemaps.
• Các trang API — list, thêm, và xóa verified properties.

Điều này exposes nhiều of điều gì bạn đã dùng trong đó interface — đó Performance báo cáo và đó URL Inspection tool — as endpoints bạn có thể script so với. Điều này không một 1:1 mirror, though: đó API không bảo đảm đầy đủ UI parity (URL Inspection trực tiếp kiểm thử, chẳng hạn, là UI-chỉ — see dưới), và neither API access nor automation on của nó own bảo đảm lập chỉ mục, thứ hạng, traffic diagnosis, hoặc AI-khả năng hiển thị trên tìm kiếm.

Auth: OAuth 2,0, hai scopes, verified properties chỉ

có không API key. Mỗi call là OAuth 2,0 — Google là rõ ràng đó “all requests to the Google Search Console API must be authorized by an authenticated user.” (bản dịch) «all các yêu cầu để đó Google Search Console API phải được authorized by an authenticated người dùng.» Bạn register an app trong Google Cloud, yêu cầu một phạm vi, và nhận một ngắn-lived access token. Hai scopes exist:

• https://www.googleapis.com/auth/webmasters — đọc/ghi.
• https://www.googleapis.com/auth/webmasters.readonly — chỉ đọc.

Cho máy chủ-để-máy chủ automation (một nightly reporting job, an chỉ mục monitor) bạn grant một service account access để đó thuộc tính và skip đó interactive consent flow.

Cho website properties, hai thuộc tính-identifier formats quan trọng ở đây cũng: một URL-prefix thuộc tính là đã truyền as một đầy đủ thuộc tính URL (Google own ví dụ là http://www.example.com/), và một Domain thuộc tính dùng đó sc-domain:example.com form — bạn có để truyền whichever form matches cách đó thuộc tính là verified trong Search Console. Either way, đó service account (hoặc người dùng) cần để là granted access để đó chính xác thuộc tính; đây là không một bypass cho quyền sở hữu hoặc một blanket grant trên mỗi thuộc tính on đó account.

Và đó gate đó trips mọi người lên: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (bản dịch) «Bạn phải có appropriate access (owner, đầy đủ, đọc) để bất kỳ Google Search Console account đó bạn wish để access dùng đó API.» Call đó API cho một thuộc tính bạn là không verified on và điều này trả về không có gì — không phải lỗi bạn’ll nhất thiết notice, chỉ empty dữ liệu.

Tìm kiếm Analytics API — đó Performance báo cáo, tại quy mô

Bắt đầu với đó ceiling, không đó convenience: Google own caveat là đó “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (bản dịch) «Đó API là bounded by internal limitations of Search Console và không bảo đảm để trả về all dữ liệu các hàng nhưng rather top ones.» Pagination extends cách far bạn có thể trang vào đó top-các hàng list — điều này không xóa đó ceiling. Khi bạn cần mỗi hàng, đó là đó cue để reach cho BigQuery bulk export (dưới), không một bigger rowLimit.

Trong đó ceiling, này là vẫn đó một hầu hết mọi người come cho. Đó reason điều này beats đó interface là đó rowLimit parameter: “[Optional; Valid range is 1–25,000; Default is 1,000].” (bản dịch) «[Tùy chọn; Hợp lệ range là 1–25 000; Default là 1 000].» Đó interface export caps near 1 000 các hàng; đó API cho bạn lên để 25 000 theo yêu cầu, và bạn paginate past đó với startRow. On một site với một dài tail of các truy vấn, đó là đó khác biệt giữa seeing đó top of của bạn dữ liệu và seeing hơn of điều này — vẫn không all of điều này.

Hai hơn điều shape điều gì xuất hiện lại. Đầu tiên, dataState controls freshness: final (đó default) trả về chỉ finalized dữ liệu, all bao gồm fresh, recently collected dữ liệu, và hourly_all cho hourly breakdowns đó là explicitly một phần — đó phản hồi metadata flags một first_incomplete_date hoặc first_incomplete_hour, và Google notes các giá trị sau đó point có thể vẫn thay đổi. Second, Tìm kiếm Analytics quotas không một single number: đó usage limits trang splits them vào load limits (một tài nguyên-based allowance measured trong 10-minute và 1-day chunks — wider date ranges, hơn dimensions, và heavier filtering all draw điều này xuống nhanh hơn) và đó QPS/QPM/QPD yêu cầu-rate limits covered dưới. Bạn có thể hit đó load ceiling trước khi bạn hit đó yêu cầu-rate ceiling.

URL Inspection API — và đó quota đó thực ra constrains bạn

Đó URL Inspection API “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (bản dịch) «view[s] đó được lập chỉ mục, hoặc indexable, status of đó provided URL. Presently chỉ đó status of đó version trong đó Google chỉ mục là khả dụng; bạn không thể kiểm thử đó indexability of một trực tiếp URL.» Đó cuối cùng clause là một real phạm vi limit, không một technicality: đó interface URL Inspection tool có thể chạy một trực tiếp kiểm thử so với đó trang as điều này tồn tại hiện tại; đó API có thể chỉ báo cáo on đó version Google đã có được lập chỉ mục. Dùng đó API để xây dựng chỉ mục-coverage monitoring trên nhiều URLs — không as một substitute cho đó UI trực tiếp kiểm thử.

Ở đây nơi đó math matters. Theo site, bạn nhận 2 000 các truy vấn theo day và 600 theo minute. (Theo project đó ceiling là far cao hơn — 10 000 000/day và 15 000/minute — nhưng đó theo-site cap là điều gì bites.) Nếu bạn muốn để monitor đó chỉ mục status of một 50 000-URL site, bạn không thể inspect them all trong một day; bạn batch và schedule trên days, hoặc bạn prioritize. Một vài posts làm này arithmetic, và đây là đó single biggest planning constraint on lớn-quy mô chỉ mục monitoring.

By contrast, Tìm kiếm Analytics là generous — 1 200 QPM theo site và theo người dùng — và đó other các tài nguyên (Sitemaps, Các trang) sit tại 20 QPS / 200 QPM theo người dùng. URL Inspection là đó tight một.

Sitemaps và Các trang APIs

Đó Sitemaps API là đó management layer cho của bạn sitemaps: điều này “submits a sitemap for a site,” (bản dịch) «submits một sitemap cho một site,» “deletes a sitemap from this site,” (bản dịch) «deletes một sitemap từ này site,» “retrieves information about a specific sitemap,” (bản dịch) «retrieves information về một cụ thể sitemap,» và “lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (bản dịch) «lists đó sitemaps-entries được gửi cho này site, hoặc được bao gồm trong đó sitemap chỉ mục file.» Đó sitemap tài nguyên điều này trả về bao gồm các trường như path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors, và một contents array — handy cho auditing sitemap health tại quy mô.

Đó Các trang API lists, adds, và xóa verified properties — hữu ích nếu bạn manage nhiều properties và muốn để provision hoặc audit them programmatically.

Khi nào nên dùng BigQuery bulk export thay vì

Đối với các trang web lớn, đó API 25 000-các hàng-theo-yêu cầu, top-các hàng-chỉ model becomes một ceiling. Google câu trả lời không một fifth API tài nguyên đó trả về đó giống nhau shape of dữ liệu — đây là một tách biệt, scheduled export pipeline: đó bulk dữ liệu export để BigQuery. Think of đó lựa chọn as pull so với. scheduled push, không “API A vs. API B.” (bản dịch) «API MỘT so với. API B.» Google own cách diễn đạt: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (bản dịch) «Schedule một daily export of của bạn Search Console performance dữ liệu để BigQuery, nơi bạn có thể chạy phức tạp các truy vấn over của bạn dữ liệu hoặc export điều này để an external storage service. Dùng đó bulk dữ liệu export feature, bạn’ll see all đó performance dữ liệu khả dụng để Search Console cho của bạn thuộc tính, với đó exception of ẩn danh các truy vấn.»

đó là đó decision rule:

• Interface export — ~1 000 các hàng, nhanh một-off look.
• Tìm kiếm Analytics API — lên để 25 000 các hàng/yêu cầu, paginate, scriptable; great cho moderate on-demand pulls và dashboards.
• BigQuery bulk export — all khả dụng performance dữ liệu, daily, không hàng cap; đó right tool khi bạn đã nhận tens of thousands of các trang hoặc các truy vấn.

Đó một điều none of them cho bạn là ẩn danh các truy vấn — đó terms Google hides cho quyền riêng tư. đó là một real khoảng trống, không một bug bạn có thể hoạt động khoảng. I know đó quy mô of điều này firsthand: as Ahrefs’ Brand Ambassador I helped surface một nghiên cứu nơi we pulled all đó dữ liệu khả dụng từ đó API trên một very lớn sample of các trang và được tìm thấy Google hides đó từ khóa term on một lớn share of clicks. We sau đó được xây dựng đó vào Ahrefs Xếp hạng Tracker — đầy đủ history of của bạn GSC dữ liệu, đó percent of clicks going để ẩn danh các truy vấn, và một custom CTR curve được xây dựng từ của bạn own numbers. Khi ai đó tells bạn đó API trả về “all your data,” (bản dịch) «all của bạn dữ liệu,» đó ẩn danh slice là đó honest asterisk.

Phổ biến dùng cases

• Automated reporting — scheduled pulls vào Sheets hoặc một warehouse.
• BI dashboards — Looker Studio hoặc BigQuery on top of đó Performance dữ liệu.
• Lớn-quy mô chỉ mục/coverage monitoring — URL Inspection, batched trong đó 2 000/day quota.
• CTR curve building — model dự kiến CTR by position từ của bạn own dữ liệu.
• Anomaly alerting — flag nhấp/impression drops tự động.

Này là cũng cách bên thứ ba tools hoạt động: khi Ahrefs hoặc một Looker Studio connector “integrates Search Console,” (bản dịch) «integrates Search Console,» họ là calling những giống nhau APIs (và increasingly, đó BigQuery export) on của bạn behalf.

AI summary

MỘT condensed take on đó Advanced version:

• Đó Search Console API = four REST APIs dưới webmaster-tools/v1: Tìm kiếm Analytics (Performance dữ liệu), URL Inspection (chỉ mục status), Sitemaps, và Các trang. đây là không đầy đủ UI parity — vài điều, như URL Inspection trực tiếp kiểm thử, chỉ exist trong đó interface, và API access alone không bảo đảm lập chỉ mục, thứ hạng, hoặc traffic diagnosis.
• Auth là OAuth 2,0, không API key. Hai scopes (webmasters, webmasters.readonly); service accounts cho máy chủ-để-máy chủ, nhưng they vẫn cần rõ ràng access để đó chính xác thuộc tính. siteUrl takes either một URL-prefix thuộc tính hoặc một sc-domain:example.com Domain thuộc tính — match cách đây là verified. Đó API chỉ trả về dữ liệu cho properties bạn đã verified — đó #1 beginner gotcha.
• Tìm kiếm Analytics trả về top các hàng đầu tiên, không một hoàn tất dump — “does not guarantee to return all data rows but rather top ones,” (bản dịch) «không bảo đảm để trả về all dữ liệu các hàng nhưng rather top ones,» regardless of pagination. Trong đó ceiling: 1–25 000 các hàng theo yêu cầu (default 1 000), so với ~1 000 trong đó interface export, và quotas split vào load limits và QPS/QPM/QPD yêu cầu-rate limits.
• URL Inspection: 2 000 các truy vấn/day, 600/minute theo site, và điều này các báo cáo chỉ đó được lập chỉ mục version — điều này không thể chạy một trực tiếp kiểm thử. Đó quota là đó real constraint on lớn-quy mô chỉ mục monitoring — batch và schedule khoảng điều này.
• Sitemaps API lists/nhận/submits/deletes sitemaps; Các trang API lists/adds/xóa properties.
• Đối với các trang web lớn, dùng đó BigQuery bulk dữ liệu export — một tách biệt scheduled pipeline (không một fifth API tài nguyên) giving all khả dụng performance dữ liệu daily, không hàng cap, except ẩn danh các truy vấn.
• Ẩn danh các truy vấn là một genuine khoảng trống không API hoặc export fills — Patrick Ahrefs hoạt động quantified cách lớn đó hidden slice là.

Tài liệu chính thức

Chính-nguồn tài liệu từ Google.

Search Console API reference

• Search Console API — Overview / về — điều gì đó API làm và đó verified-thuộc tính requirement.
• Tìm kiếm Analytics: query reference — đó rowLimit (1–25 000) và dimension parameters.
• URL Inspection API reference — điều gì chỉ mục-status dữ liệu đó inspect phương thức trả về.
• Sitemaps API reference — list, nhận, submit, delete.
• Các trang API reference — list, thêm, xóa verified properties.
• Usage limits — đó đầy đủ theo-site, theo-người dùng, và theo-project quota bảng.
• Authorizing các yêu cầu (OAuth 2,0) — scopes và đó auth flow.

Bulk dữ liệu export

• Về bulk dữ liệu export (Search Console Help) — schedule một daily BigQuery export of all performance dữ liệu except ẩn danh các truy vấn.
• Bulk dữ liệu export announcement (Tìm kiếm Central blog) — đó launch post positioning bulk export đối với các trang web lớn.

Quotes từ đó nguồn

On-đó-record statements từ Google tài liệu. Mỗi link là một deep link đó jumps để đó quoted passage on đó trang nguồn.

Google — điều gì đó API làm và ai có thể dùng điều này

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (bản dịch) «view, thêm, hoặc xóa properties và sitemaps, chạy advanced các truy vấn cho Google Search kết quả dữ liệu cho đó properties đó bạn manage trong Search Console, và kiểm thử riêng lẻ các trang.» — Google Search Console API tài liệu (Overview). Nhảy đến trích dẫn
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (bản dịch) «Bạn phải có appropriate access (owner, đầy đủ, đọc) để bất kỳ Google Search Console account đó bạn wish để access dùng đó API.» — Google Search Console API tài liệu (Overview). Nhảy đến trích dẫn
• “All requests to the Google Search Console API must be authorized by an authenticated user.” (bản dịch) «All các yêu cầu để đó Google Search Console API phải được authorized by an authenticated người dùng.» — Authorizing các yêu cầu hướng dẫn. Nhảy đến trích dẫn

Google — Tìm kiếm Analytics API

• “[Optional; Valid range is 1–25,000; Default is 1,000]” (bản dịch) «[Tùy chọn; Hợp lệ range là 1–25 000; Default là 1 000]» — đó rowLimit parameter. — Tìm kiếm Analytics: query reference. Nhảy đến trích dẫn
• “The URL of the property as defined in Search Console.” (bản dịch) «Đó URL of đó thuộc tính as được định nghĩa trong Search Console.» — đó siteUrl parameter, whose các ví dụ cho cả hai đó URL-prefix form (http://www.example.com/) và đó Domain-thuộc tính form (sc-domain:example.com). — Tìm kiếm Analytics: query reference. Nhảy đến trích dẫn
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (bản dịch) «Đó API là bounded by internal limitations of Search Console và không bảo đảm để trả về all dữ liệu các hàng nhưng rather top ones.» — Tìm kiếm Analytics: query reference. Nhảy đến trích dẫn

Google — URL Inspection API

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (bản dịch) «View đó được lập chỉ mục, hoặc indexable, status of đó provided URL. Presently chỉ đó status of đó version trong đó Google chỉ mục là khả dụng; bạn không thể kiểm thử đó indexability of một trực tiếp URL.» — URL Inspection API reference. Nhảy đến trích dẫn

Google — Sitemaps API

• “Submits a sitemap for a site.” (bản dịch) «Submits một sitemap cho một site.» / “Deletes a sitemap from this site.” (bản dịch) «Deletes một sitemap từ này site.» / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (bản dịch) «Lists đó sitemaps-entries được gửi cho này site, hoặc được bao gồm trong đó sitemap chỉ mục file.» — Sitemaps API reference. Nhảy đến trích dẫn

Google — bulk dữ liệu export

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (bản dịch) «Schedule một daily export of của bạn Search Console performance dữ liệu để BigQuery… bạn’ll see all đó performance dữ liệu khả dụng để Search Console cho của bạn thuộc tính, với đó exception of ẩn danh các truy vấn.» — Search Console Help: Về bulk dữ liệu export. Nhảy đến trích dẫn

OAuth setup & đầu tiên-call checklist

Getting từ zero để một hoạt động Search Console API call:

• Xác nhận bạn có verified access (owner, đầy đủ, hoặc đọc) để đó thuộc tính trong Search Console — đó API trả về không có gì cho unverified properties.
• Tạo một project trong đó Google Cloud Console.
• Enable đó Search Console API cho đó project.
• Tạo credentials: an OAuth 2,0 client (cho interactive/người dùng apps) hoặc một service account (cho máy chủ-để-máy chủ automation).
• Nếu dùng một service account, grant điều này access để đó thuộc tính trong Tìm kiếm Console settings.
• Yêu cầu đó right phạm vi: webmasters.readonly cho reporting, webmasters nếu bạn’ll submit sitemaps hoặc manage properties.
• Obtain an access token qua đó OAuth flow (hoặc service-account key).
• Xác nhận đó siteUrl format matches cách đó thuộc tính là verified: một đầy đủ URL cho một URL-prefix thuộc tính, hoặc sc-domain:example.com cho một Domain thuộc tính.
• Làm một kiểm thử call để searchAnalytics.query với một nhỏ date range và rowLimit: 10 để xác nhận dữ liệu xuất hiện lại.
• Plan khoảng quotas: Tìm kiếm Analytics yêu cầu rates là generous nhưng cũng draw xuống một tách biệt load quota; URL Inspection là capped tại 2 000/day, 600/min theo site — batch accordingly. không expect URL Inspection để chạy một trực tiếp kiểm thử — đó là UI-chỉ.
• Cho tens of thousands of các hàng, set lên đó BigQuery bulk export thay vì of paginating.

Đó mental models

1. Four APIs, một auth. Tìm kiếm Analytics (đọc của bạn Performance dữ liệu), URL Inspection (đọc một URL’s chỉ mục status), Sitemaps (manage sitemaps), Các trang (manage properties). All four go qua đó giống nhau OAuth 2,0 door và respect đó giống nhau verified-thuộc tính rule.

2. Đó dữ liệu-quy mô ladder. Pick đó tool by volume:

• Nhanh look → interface export (~1 000 các hàng).
• Scriptable, moderate → Tìm kiếm Analytics API (lên để 25 000/yêu cầu, paginate).
• Lớn site, hoàn tất → BigQuery bulk export (all dữ liệu, daily, không hàng cap). Move lên đó ladder khi đó rung dưới dừng fitting của bạn dữ liệu.

3. Top các hàng, không all các hàng. Internalize đó API trả về “top ones,” không mọi thứ, và đó ẩn danh các truy vấn là excluded từ cả hai đó API và đó export. Nếu tính đầy đủ matters, BigQuery là closer — nhưng đó ẩn danh slice là đã biến mất regardless.

4. Quota arithmetic trước khi bạn xây dựng. Trước designing an chỉ mục monitor, làm đó math: URL Inspection là 2 000/day theo site. MỘT 50k-URL site không thể là inspected daily — so batch, prioritize, hoặc schedule trên days. Design khoảng đó cap, không discover điều này trong production.

Search Console API — bảng tra nhanh

Đó four APIs và của họ key limits

Auth

• OAuth 2,0 chỉ — không API key.
• Scopes: webmasters (đọc/ghi), webmasters.readonly (đọc).
• Service accounts cho máy chủ-để-máy chủ (grant them thuộc tính access).
• Chỉ verified properties trả về dữ liệu.

Fast facts

• API trả về top các hàng chỉ — không guaranteed hoàn tất — regardless of pagination.
• Interface export caps near 1 000 các hàng; API cho lên để 25 000/yêu cầu, paginate với startRow.
• Tìm kiếm Analytics quotas split vào load limits (tài nguyên-based, 10-min / 1-day chunks) và đó QPS/QPM/QPD yêu cầu-rate limits trên.
• siteUrl takes một URL-prefix thuộc tính (http://www.example.com/) hoặc một Domain thuộc tính (sc-domain:example.com) — match cách đây là verified.
• URL Inspection các báo cáo đó được lập chỉ mục version chỉ — điều này không thể chạy một trực tiếp kiểm thử; đó là UI-chỉ.
• Ẩn danh các truy vấn là excluded từ đó API và đó BigQuery export.
• Cho tens of thousands of các hàng → BigQuery bulk dữ liệu export — một tách biệt scheduled pipeline, không một fifth API tài nguyên.
• Exposes nhiều of đó Performance báo cáo (Tìm kiếm Analytics) và đó URL Inspection tool, nhưng không đầy đủ UI parity.

MỘT minimal Tìm kiếm Analytics yêu cầu

Này là illustrative, không sao chép và dán-ready — bạn’ll cần để wire lên của bạn own OAuth credentials và adjust đó dates và thuộc tính. Điều này cho thấy đó shape of một searchAnalytics.query call: đó thân yêu cầu với một date range, đó dimensions bạn muốn, và đó rowLimit.

Đó thân yêu cầu (đó part đó matters)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Sketch trong Python (với đó google-api-python-client library)

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

Để go past 25 000 các hàng, loop và increment startRow by 25 000 until một yêu cầu trả về không các hàng. Remember đó kết quả là vẫn “top các hàng,” không một hoàn tất dump — cho đó, dùng đó BigQuery bulk export.

Tools đó dùng (hoặc wrap) đó Search Console API

• Google Cloud Console — nơi bạn tạo đó project, enable đó API, và mint OAuth/service-account credentials.
• Chính thức client libraries — Google API client libraries cho Python, Java, JavaScript/Node, PHP, và .NET wrap đó REST calls.
• BigQuery — đó đích cho đó bulk dữ liệu export; query all của bạn performance dữ liệu với SQL.
• Looker Studio — connects để Search Console (và BigQuery) cho dashboards được xây dựng on đó giống nhau dữ liệu.
• Ahrefs — integrates đó Search Console API; của nó Xếp hạng Tracker cho thấy đầy đủ GSC history, đó share of clicks going để ẩn danh các truy vấn, và một custom CTR curve từ của bạn own dữ liệu.
• Search Console interface — đó Performance báo cáo và URL Inspection tool là đó manual counterparts để đó Tìm kiếm Analytics và URL Inspection APIs, với một khoảng trống đó API không thể close: chỉ đó interface tool có thể chạy một trực tiếp kiểm thử on một URL.

Prompts cho planning Search Console API hoạt động

Dùng những prompts để shape code hoặc an analysis plan. Giữ credentials, refresh tokens, và service-account keys out of bất kỳ chat input.

Design một Tìm kiếm Analytics yêu cầu

Paste của bạn thuộc tính URL, date range, dimensions, filters, và reporting goal.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Plan một quota-safe URL Inspection schedule

Paste một CSV summary hoặc được tính by URL priority thay vì confidential tokens.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

Chọn API versus BigQuery export

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Các tài nguyên worth của bạn time

My related hoạt động

• Ahrefs blog — my posts — including đó hoạt động on GSC dữ liệu tại quy mô và ẩn danh các truy vấn.
• Hiện tại trong Ahrefs Xếp hạng Tracker: đầy đủ GSC history + ẩn danh-query share — đó CTR-curve và GSC-history feature I announced.

Google tài liệu

• Search Console API overview và đó usage limits trang — đó hai các trang để bookmark đầu tiên.
• Về bulk dữ liệu export — khi và cách move để BigQuery.

Từ others

• Hidden từ khóa trong GSC — đó Ahrefs nghiên cứu (Search Engine Journal coverage) — bên thứ ba ghi-lên of đó ẩn danh-query findings.
• Enhanced Search Console analytics với BigQuery (SEJ) — một practical xem đó bulk-export path.
• Bulk dữ liệu export: một new và powerful way để access của bạn Search Console dữ liệu (Google Search Central blog) — đó Feb 2023 launch post từ đó Search Console team positioning bulk export đối với các trang web lớn.
• google-api-python-client (PyPI) — đó chính thức Python client library được dùng để call đó Search Console API; cũng khả dụng cho Node, Java, PHP, và .NET qua đó Google APIs client library family.
• r/TechSEO — đó community cho API và dữ liệu-pull khắc phục sự cố.

Số liệu worth citing

• Tìm kiếm Analytics hàng limit: 25 000 theo yêu cầu (default 1 000) — versus đó interface export ~1 000-hàng cap. Này là đó cốt lõi reason để dùng đó API. Nguồn
• URL Inspection quota: 2 000 các truy vấn/day và 600/minute theo site — đó hard ceiling on lớn-quy mô chỉ mục monitoring (10M/day, 15 000/min theo project). Nguồn
• Ẩn danh các truy vấn là excluded từ ngay cả đó hầu hết hoàn tất path (BigQuery bulk export) — một real, unavoidable khoảng trống trong của bạn query dữ liệu. Nguồn
• Google hides đó từ khóa term on một lớn share of clicks — từ đó Ahrefs nghiên cứu I helped surface, mà pulled all khả dụng dữ liệu từ đó API trên một very lớn sample of các trang. Coverage

Tự kiểm tra: Search Console API

Five nhanh các câu hỏi on đó APIs, authentication, dữ liệu limits, và quy mô. Pick an câu trả lời cho mỗi, thì kiểm tra của bạn kết quả.

Nhật ký thay đổi