Analytics SEO API 的入门教程与使用指南

一、为何选择 Analytics SEO API？

自动化报表获取：利用 runReport 方法，定时拉取 sessions、pageViews、bounceRate、Conversion Rate 等核心指标。
精准关键词分析：通过 Search Console API 获取 queries、clicks、impressions、CTR、averagePosition，量化长尾关键词价值。
API-first SEO 流程：将 SEO 数据与 ETL、BigQuery、Looker Studio 深度集成，构建自动化 SEO 仪表盘 和 AIOps 异常检测。
跨平台数据对比：对接 Google Analytics Data API、Search Console API 与 Google Ads API，实现自然流量与付费流量的 ROI 分析。

二、快速上手：环境配置与授权

启用 API
- 在 Google Cloud Console 中分别启用 Analytics Data API v1 和 Search Console API。
创建服务账号
- 为项目创建服务账号，赋予 Analytics Viewer 与 Search Console Reader 角色，下载 JSON 凭证。

设置环境变量

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"

安装 SDK

pip install google-analytics-data google-api-python-client

三、核心 API：runReport 方法实战

3.1 拉取基础流量指标

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import RunReportRequest, DateRange, Dimension, Metric

client = BetaAnalyticsDataClient()
request = RunReportRequest(
    property="properties/123456789",
    date_ranges=[DateRange(start_date="2025-07-01", end_date="2025-07-31")],
    dimensions=[Dimension(name="sessionDefaultChannelGroup")],
    metrics=[Metric(name="sessions"), Metric(name="pageViews"), Metric(name="bounceRate")],
)
response = client.run_report(request)
for row in response.rows:
    print(f"{row.dimension_values[0].value}: Sessions={row.metric_values[0].value}, "
          f"PageViews={row.metric_values[1].value}, BounceRate={row.metric_values[2].value}%")

维度：sessionDefaultChannelGroup、pagePath
指标：sessions、pageViews、bounceRate

3.2 转化率评估示例

from google.analytics.data_v1beta.types import FilterExpression, Filter

request.metrics.append(Metric(name="eventCount"))
request.dimension_filter = FilterExpression(
    filter=Filter(field_name="eventName", string_filter={"value": "purchase"})
)
response = client.run_report(request)
for row in response.rows:
    sessions = int(row.metric_values[0].value)
    purchases = int(row.metric_values[1].value)
    cr = purchases / sessions * 100 if sessions else 0
    print(f"{row.dimension_values[0].value}: CR={cr:.2f}%")

Conversion Rate (CR)：purchases ÷ sessions × 100%

四、关键词表现：Search Console API 使用

4.1 拉取查询数据

from googleapiclient.discovery import build

sc = build('searchconsole', 'v1', credentials=creds)
response = sc.searchanalytics().query(
    siteUrl='https://www.example.com',
    body={
        "startDate": "2025-07-01",
        "endDate": "2025-07-31",
        "dimensions": ["query", "page"],
        "rowLimit": 200
    }
).execute()

for row in response.get('rows', []):
    query, page = row['keys']
    clicks = row['clicks']; imp = row['impressions']
    ctr = row['ctr']; pos = row['position']
    print(f"{query} → {page}: Clicks={clicks}, Impressions={imp}, CTR={ctr:.2%}, AvgPos={pos:.2f}")

核心指标：clicks、impressions、CTR、averagePosition

4.2 流量—转化全链路分析

将 GA4 Data API 获取的 sessions 与 GSC API 获取的 impressions/ctr 按 page 或 query 聚合，实现 SEO 深度洞察。

五、批量报告与自动化管道

批量导出
- 使用 batchRunReports 处理大规模行数数据。
数据存储
- 将原始数据写入 BigQuery、PostgreSQL 或 CSV。
ETL 处理
- 定期计算关键 KPI：CR、CTR、AvgPos。
可视化呈现
- 利用 Looker Studio、Grafana JSON API 构建 SEO 仪表盘。
自动告警
- 配置 Cloud Monitoring 或 Alertmanager，当 CR < 1% 或 CTR 异常时自动通知。