Google Search Console API: Complete Developer GuideGoogle Search Console API：完整开发者指南

What does the Google Search Console API do?Google Search Console API 能做什么？

The Google Search Console API gives authorized applications programmatic access to selected Search Console data and actions. A client can list accessible properties, query Search Analytics performance, list or manage sitemaps, and inspect the indexed status of URLs. It is best suited to repeatable extraction, governed reporting, portfolio monitoring, and diagnostic workflows.

Google Search Console API 允许已获授权的应用以程序方式访问部分 Search Console 数据与操作。客户端可以列出可访问资源、查询 Search Analytics 表现、列出或管理站点地图，以及检查 URL 在 Google 索引中的状态。它适合周期提取、受治理报告、站点组合监控与诊断流程。

Plan the pipeline before writing the first request在发出第一个请求前规划数据管道

A production integration has four boundaries: identity, extraction, evidence, and operations. Separate them so a token refresh, schema change, quota event, or analyst mistake cannot silently rewrite history.

生产级集成包含身份、提取、证据与运维四个边界。应将它们分离，避免令牌刷新、结构变化、配额事件或分析误操作悄悄改写历史。

Choose the API resource that matches the question根据问题选择正确的 API 资源

Do not treat the API as one dataset. Its resources answer different questions and use different endpoints, response models, limits, and operating cadences.

不要把 API 当成单一数据集。不同资源回答不同问题，并具有不同端点、响应模型、限制与运行节奏。

Design OAuth and property permissions deliberately有意识地设计 OAuth 与资源权限

Enable the Search Console API in a Google Cloud project, configure the OAuth consent flow, create the appropriate client, and request the smallest useful scope. The read-only scope is sufficient for performance queries and inspection; sitemap mutations require a write-capable scope. The authenticated principal must also have the necessary permission on each Search Console property.

在 Google Cloud 项目中启用 Search Console API，配置 OAuth 同意流程，创建合适客户端，并申请满足需求的最小范围。只读范围可用于表现查询与检查；站点地图变更需要可写范围。认证主体还必须拥有每个 Search Console 资源所需权限。

Never ship a client secret in browser code, commit tokens to a repository, or assume Google Cloud IAM automatically grants Search Console property access. Record who authorized the client, which scopes were granted, and when credentials expire or rotate.

不要在浏览器代码中发布客户端密钥，不要把令牌提交到代码仓库，也不要假设 Google Cloud IAM 会自动赋予 Search Console 资源权限。应记录授权人、授予范围以及凭据到期或轮换时间。

Compose Search Analytics requests around one analytical grain围绕单一分析粒度构造 Search Analytics 请求

Define the property, inclusive date range, search type, dimensions, filters, aggregation, and data state as a versioned query contract. Dates use Pacific Time. Dimension order determines the order of keys in each response row. When page or query is grouped or filtered, query cost rises and aggregation choices narrow.

将资源、包含首尾的日期范围、搜索类型、维度、过滤、聚合与数据状态定义为可版本化查询契约。日期按太平洋时间解释。维度顺序决定响应行中键值顺序。按页面或查询分组、过滤时，查询成本会上升，聚合选择也会受限。

{
  "startDate": "2026-06-01",
  "endDate": "2026-06-30",
  "dimensions": ["date", "page", "query"],
  "type": "web",
  "dimensionFilterGroups": [{
    "groupType": "and",
    "filters": [{
      "dimension": "country",
      "operator": "equals",
      "expression": "usa"
    }]
  }],
  "aggregationType": "auto",
  "dataState": "final",
  "rowLimit": 25000,
  "startRow": 0
}

Start with a data-presence request grouped only by date. Then add one dimension or filter at a time and preserve the exact request beside the response. This makes empty results, aggregation shifts, and filter mistakes easier to diagnose.

先使用仅按日期分组的数据存在性请求，再逐步加入维度或过滤，并把完整请求与响应一同保存。这样更容易诊断空结果、聚合变化与过滤错误。

Paginate until the API returns fewer rows than requested持续分页，直到返回行数少于请求数量

The valid rowLimit range is 1 to 25,000. Request a batch, persist it, increment startRow by the number returned, and stop only when the batch contains fewer rows than requested. If a boundary lands exactly on a full batch, the next request may correctly return zero rows.

rowLimit 有效范围为 1 到 25,000。请求一批、持久化、按实际返回数量递增 startRow，仅在该批少于请求数量时停止。如果边界正好落在完整批次上，下一次请求可能正常返回零行。

start_row = 0
page_size = 25_000

while True:
    body = {**query_contract,
            "rowLimit": page_size,
            "startRow": start_row}
    response = service.searchanalytics().query(
        siteUrl=site_url, body=body).execute()
    rows = response.get("rows", [])
    persist_raw_batch(run_id, start_row, body, response)
    if len(rows) < page_size:
        break
    start_row += len(rows)

Pagination does not remove the platform's data-availability limits. Google states that Search Analytics is bounded by internal limitations and does not guarantee every possible row. Treat the extract as reported top-row evidence, not a complete census of all searches.

分页不会消除平台的数据可用性限制。Google 明确说明 Search Analytics 受内部限制约束，并不保证返回所有可能行。应把提取结果视为已报告的顶部数据证据，而不是所有搜索的完整普查。

Separate finalized extracts from fresh operational views将最终数据提取与新鲜运营视图区分开

Use dataState: final for stable recurring reporting. Use all or hourly_all only when the workflow can display and later replace incomplete data. When recent data is requested, response metadata can identify the first incomplete date or hour. Store that boundary with every run.

稳定周期报告应使用 dataState: final。只有在流程能够标记并随后替换不完整数据时，才使用 all 或 hourly_all。请求近期数据时，响应元数据可指出第一个不完整日期或小时，应把该边界与每次运行一同保存。

Use URL Inspection for indexed-state evidence, not live testing用 URL Inspection 获取索引状态证据，而非实时测试

Send the fully qualified inspection URL and its Search Console property identifier. The URL must belong to that property. The response can include index status, referring URLs, known sitemaps, last crawl information, canonical signals, mobile usability, and rich-result analysis when available.

发送完整检查 URL 及其 Search Console 资源标识，URL 必须属于该资源。响应可包含索引状态、引荐 URL、已知站点地图、最近抓取信息、规范化信号、移动可用性以及可用时的富媒体结果分析。

Inspect representative templates and exception cohorts instead of blindly scanning every URL. Store the inspection time and response, schedule rechecks after meaningful releases, and respect the separate URL Inspection quota.

应检查代表性模板与异常分组，而不是盲目扫描全部 URL。保存检查时间与响应，在重要发布后安排复查，并遵守独立的 URL Inspection 配额。

Engineer for load quotas, rate limits, and retries针对负载配额、速率限制与重试进行工程设计

Search Analytics has short-term and long-term load quotas as well as call-rate quotas. Long date ranges and requests grouped or filtered by page and query are more expensive. URL Inspection and other resources have separate limits. Quotas can change, so read the official limits page during implementation and monitor the Cloud project quota console.

Search Analytics 同时受短期、长期负载配额与调用速率约束。长日期范围以及同时按页面和查询分组或过滤的请求成本更高。URL Inspection 与其他资源有独立限制。配额可能变化，实施时应核对官方限制页并监控 Cloud 项目配额控制台。

Put data-quality gates between extraction and reporting在数据提取与报告之间设置质量门

A successful HTTP response proves transport, not analytical correctness. Validate the property, requested period, completeness status, expected schema, dimension-key count, row counts, duplicates, metric ranges, aggregation type, and abrupt distribution changes before publishing downstream tables.

HTTP 成功响应只能证明传输成功，不能证明分析正确。发布下游表之前，应验证资源、请求周期、完整状态、预期结构、维度键数量、行数、重复项、指标范围、聚合类型与异常分布变化。

Diagnose errors by layer instead of retrying everything按层诊断错误，而不是对所有错误重试

Log request IDs, status, sanitized error details, property, operation, attempt count, delay, and final disposition. Never log access tokens or client secrets.

记录请求 ID、状态、脱敏错误详情、资源、操作、尝试次数、延迟与最终处置。不要记录访问令牌或客户端密钥。

Store raw evidence and modeled tables separately分别存储原始证据与建模表

Keep an immutable raw layer for reproducibility and a curated layer for analysts. A durable fact-table key should include property, date, search type, aggregation, and every requested dimension. Store clicks and impressions as additive metrics only within compatible grains; recompute CTR from summed clicks and impressions, and calculate position with the appropriate impression weighting.

保留不可变原始层以支持复现，并为分析师建立整理层。稳定事实表键应包含资源、日期、搜索类型、聚合与每个请求维度。点击和展示只能在兼容粒度内累加；CTR 应从汇总点击与展示重新计算，排名则需使用恰当的展示加权。

Partition by date and property, retain the extraction run ID and contract hash, and upsert finalized periods idempotently. Avoid collapsing query and page coordinates too early; they are essential for cannibalization, CTR, content, and landing-page analysis.

按日期与资源分区，保留提取运行 ID 和契约哈希，并以幂等方式更新最终周期。不要过早合并查询与页面坐标，它们对关键词内耗、CTR、内容与落地页分析非常重要。

Monitor data freshness, coverage, cost, and reliability监控数据新鲜度、覆盖、成本与可靠性

Track successful and failed runs, authentication failures, quota responses, latency, batches, rows, bytes, latest finalized date, incomplete boundary, zero-row properties, schema drift, duplicate keys, and reconciliation variance. Alert on service-level conditions, not every isolated warning.

跟踪成功与失败运行、认证失败、配额响应、延迟、批次、行数、字节数、最新最终日期、不完整边界、零行资源、结构漂移、重复键与对账差异。应针对服务级条件告警，而不是每个孤立警告。

Turn the API into focused SEO workflows把 API 转化为聚焦的 SEO 工作流

Explore query-page evidence without building the pipeline first无需先构建管道即可探索查询—页面证据

If the immediate goal is analysis rather than infrastructure, prepare a focused Search Console export and use the InfiniSynapse GSC Data Analysis tool to explore query-page cohorts, CTR opportunities, and material movements. Validate important findings in Search Console before turning them into decisions.

如果当前目标是分析而非基础设施，可以准备聚焦的 Search Console 导出，并使用 InfiniSynapse GSC 数据分析工具探索查询—页面分组、CTR 机会与重要变化。在将结果用于决策前，应回到 Search Console 验证关键发现。

Google Search Console API production checklistGoogle Search Console API 生产检查清单

Frequently asked questions常见问题

Official Google Search Console API documentationGoogle Search Console API 官方文档

Use these primary sources when implementing or reviewing the integration. Limits and supported fields can change.

实施或复核集成时应使用以下一手资料。限制与支持字段可能变化。

A practical google search console api evidence worksheet可直接使用的“google search console api”证据工作表

Use this analysis sheet to turn google search console api data into a repeatable SEO decision. Preserve the exact GSC filters, comparison period, limitations, threshold, action owner, and recheck date.

使用这份分析表，把“google search console api”数据转化为可复现的 SEO 决定。保留完整 GSC 筛选条件、比较周期、局限、阈值、行动负责人和复查日期。

Continue with related InfiniSynapse guides:

继续阅读相关 InfiniSynapse 指南：