Back to Details

seo-google

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google SEO APIs

Google SEO API

Direct access to Google's own SEO data. Bridges the gap between crawl-based analysis (existing claude-seo skills) and Google's real-time field data: actual Chrome user metrics, real indexation status, search performance, and organic traffic.
All APIs are free. Setup requires a Google Cloud project with API key and/or service account -- run 
/seo google setup
for step-by-step instructions.
可直接获取Google官方SEO数据，填补了基于爬虫的分析（现有claude-seo技能）与Google实时真实用户数据之间的差距：涵盖真实Chrome用户指标、实际收录状态、搜索表现和自然流量。
所有API均免费使用。配置需要一个带有API密钥和/或服务账号的Google Cloud项目——运行
/seo google setup
获取分步指导。

Prerequisites

前置要求

Before executing any command, check credentials:
bash
python scripts/google_auth.py --check --json
Config file: 
~/.config/claude-seo/google-api.json
json
{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}
If missing, read 
references/auth-setup.md
and walk the user through setup.
执行任何命令前，请检查凭据：
bash
python scripts/google_auth.py --check --json
配置文件：
~/.config/claude-seo/google-api.json
json
{
  "service_account_path": "/path/to/service_account.json",
  "api_key": "AIzaSy...",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}
如果缺少配置文件，请查看
references/auth-setup.md
并引导用户完成配置。

Credential Tiers

凭据权限等级

TierDetectionAvailable Commands
0 (API Key)
api_key
present
pagespeed
, 
crux
, 
crux-history
, 
youtube
, 
nlp
1 (OAuth/SA)+ OAuth token or service accountTier 0 + 
gsc
, 
inspect
, 
sitemaps
, 
index
2 (Full)+ 
ga4_property_id
configured		Tier 1 + 
ga4
, 
ga4-pages
3 (Ads)+ 
ads_developer_token
+ 
ads_customer_id
Tier 2 + 
keywords
, 
volume
Always communicate the detected tier before running commands.
权限等级检测条件可用命令
0（API密钥）存在
api_key
pagespeed
, 
crux
, 
crux-history
, 
youtube
, 
nlp
1（OAuth/服务账号）额外拥有OAuth令牌或服务账号等级0的所有命令 + 
gsc
, 
inspect
, 
sitemaps
, 
index
2（完整权限）已配置
ga4_property_id
等级1的所有命令 + 
ga4
, 
ga4-pages
3（广告权限）额外拥有
ads_developer_token
+ 
ads_customer_id
等级2的所有命令 + 
keywords
, 
volume
运行命令前，请务必告知用户当前检测到的权限等级。

Quick Reference

快速参考

CommandWhat it doesTier
/seo google setup
Check/configure API credentials--
/seo google pagespeed <url>
PSI Lighthouse + CrUX field data0
/seo google crux <url>
CrUX field data only (p75 metrics)0
/seo google crux-history <url>
25-week CWV trend analysis0
/seo google gsc <property>
Search Console: clicks, impressions, CTR, position1
/seo google inspect <url>
URL Inspection: index status, canonical, crawl info1
/seo google inspect-batch <file>
Batch URL Inspection from file1
/seo google sitemaps <property>
GSC sitemap status1
/seo google index <url>
Submit URL to Indexing API1
/seo google index-batch <file>
Batch submit up to 200 URLs1
/seo google ga4 [property-id]
GA4 organic traffic report2
/seo google ga4-pages [property-id]
Top organic landing pages2
/seo google youtube <query>
YouTube video search (views, likes, duration)0
/seo google youtube-video <id>
YouTube video details + top comments0
/seo google nlp <url-or-text>
NLP entity extraction + sentiment + classification0
/seo google entities <url-or-text>
Entity analysis only (for E-E-A-T)0
/seo google keywords <seed>
Keyword ideas from Google Ads Keyword Planner3
/seo google volume <keywords>
Search volume lookup from Keyword Planner3
/seo google entity <query>
Knowledge Graph entity check0
/seo google safety <url>
Web Risk URL safety check0
/seo google quotas
Show rate limits for all APIs--
命令功能权限等级
/seo google setup
检查/配置API凭据--
/seo google pagespeed <url>
PSI Lighthouse检测 + CrUX真实用户数据0
/seo google crux <url>
仅CrUX真实用户数据（p75指标）0
/seo google crux-history <url>
25周Core Web Vitals趋势分析0
/seo google gsc <property>
Search Console：点击量、展示量、点击率、排名1
/seo google inspect <url>
URL检测：收录状态、规范网址、抓取信息1
/seo google inspect-batch <file>
批量检测文件中的URL1
/seo google sitemaps <property>
GSC站点地图状态1
/seo google index <url>
向Indexing API提交URL1
/seo google index-batch <file>
批量提交最多200个URL1
/seo google ga4 [property-id]
GA4自然流量报告2
/seo google ga4-pages [property-id]
热门自然流量着陆页2
/seo google youtube <query>
YouTube视频搜索（播放量、点赞数、时长）0
/seo google youtube-video <id>
YouTube视频详情 + 热门评论0
/seo google nlp <url-or-text>
NLP实体提取 + 情感分析 + 内容分类0
/seo google entities <url-or-text>
仅实体分析（用于E-E-A-T评估）0
/seo google keywords <seed>
基于Google Ads关键词规划师生成关键词创意3
/seo google volume <keywords>
基于关键词规划师查询搜索量3
/seo google entity <query>
知识图谱实体校验0
/seo google safety <url>
Web Risk URL安全检测0
/seo google quotas
显示所有API的调用限制--

PageSpeed + CrUX

PageSpeed + CrUX

/seo google pagespeed <url>

/seo google pagespeed <url>

Combined Lighthouse lab data + CrUX field data.
Script: 
python scripts/pagespeed_check.py <url> --json
Reference: 
references/pagespeed-crux-api.md
Default: Both mobile + desktop strategies, all Lighthouse categories.
Output merges lab scores (point-in-time Lighthouse) with field data (28-day Chrome user metrics). CrUX tries URL-level first, falls back to origin-level.
结合Lighthouse实验室数据 + CrUX真实用户数据。
脚本： 
python scripts/pagespeed_check.py <url> --json
参考文档： 
references/pagespeed-crux-api.md
默认设置： 同时检测移动端和桌面端，覆盖所有Lighthouse检测类别。
输出结果融合实验室评分（实时Lighthouse检测）与真实用户数据（28天Chrome用户指标）。CrUX优先使用URL级别数据，若无则回退至域名级别数据。

/seo google crux <url>

/seo google crux <url>

CrUX field data only (no Lighthouse run). Faster.
Script: 
python scripts/pagespeed_check.py <url> --crux-only --json
仅提供CrUX真实用户数据（不运行Lighthouse检测），速度更快。
脚本： 
python scripts/pagespeed_check.py <url> --crux-only --json

/seo google crux-history <url>

/seo google crux-history <url>

25-week CrUX History trends. Shows whether CWV metrics are improving, stable, or degrading.
Script: 
python scripts/crux_history.py <url> --json
Reference: 
references/pagespeed-crux-api.md
Output includes per-metric trend direction, percentage change, and weekly p75 values.
25周CrUX历史趋势数据，展示Core Web Vitals指标的提升、稳定或下降趋势。
脚本： 
python scripts/crux_history.py <url> --json
参考文档： 
references/pagespeed-crux-api.md
输出内容包含各指标的趋势方向、百分比变化及每周p75数值。

Search Console

Search Console

/seo google gsc <property>

/seo google gsc <property>

Search Analytics: clicks, impressions, CTR, position for last 28 days.
Script: 
python scripts/gsc_query.py --property <property> --json
Reference: 
references/search-console-api.md
Default: 28 days, dimensions=query,page, type=web, limit=1000.
Includes quick-win detection: queries at position 4-10 with high impressions.
搜索分析：最近28天的点击量、展示量、点击率、排名数据。
脚本： 
python scripts/gsc_query.py --property <property> --json
参考文档： 
references/search-console-api.md
默认设置： 28天周期，维度=查询词、页面，类型=网页，限制=1000条。
包含快速优化机会检测：排名4-10位且展示量高的查询词。

/seo google inspect <url>

/seo google inspect <url>

URL Inspection: real indexation status from Google.
Script: 
python scripts/gsc_inspect.py <url> --json
Returns: verdict (PASS/FAIL), coverage state, robots.txt status, indexing state, page fetch state, canonical selection, mobile usability, rich results.
URL检测：获取Google的实际收录状态。
脚本： 
python scripts/gsc_inspect.py <url> --json
返回内容：检测结果（通过/失败）、覆盖状态、robots.txt状态、收录状态、页面抓取状态、规范网址选择、移动端适配性、富媒体结果。

/seo google inspect-batch <file>

/seo google inspect-batch <file>

Batch inspection from a file (one URL per line). Rate limited to 2,000/day per site.
Script: 
python scripts/gsc_inspect.py --batch <file> --json
批量检测文件中的URL（每行一个URL），每个站点每日限制2000次调用。
脚本： 
python scripts/gsc_inspect.py --batch <file> --json

/seo google sitemaps <property>

/seo google sitemaps <property>

List submitted sitemaps with status, errors, warnings.
Script: 
python scripts/gsc_query.py sitemaps --property <property> --json
列出已提交的站点地图及其状态、错误和警告信息。
脚本： 
python scripts/gsc_query.py sitemaps --property <property> --json

Indexing API

Indexing API

/seo google index <url>

/seo google index <url>

Notify Google of a URL update.
Script: 
python scripts/indexing_notify.py <url> --json
Reference: 
references/indexing-api.md
The Indexing API is officially for JobPosting and BroadcastEvent/VideoObject pages. Always inform the user of this restriction. Daily quota: 200 publish requests.
通知Google更新URL。
脚本： 
python scripts/indexing_notify.py <url> --json
参考文档： 
references/indexing-api.md
Indexing API官方仅适用于JobPosting和BroadcastEvent/VideoObject类型页面，请务必告知用户此限制。每日配额：200条发布请求。

/seo google index-batch <file>

/seo google index-batch <file>

Batch submit URLs from a file. Tracks quota usage.
Script: 
python scripts/indexing_notify.py --batch <file> --json
批量提交文件中的URL，跟踪配额使用情况。
脚本： 
python scripts/indexing_notify.py --batch <file> --json

GA4 Traffic

GA4流量

/seo google ga4 [property-id]

/seo google ga4 [property-id]

Organic traffic report: daily sessions, users, pageviews, bounce rate, engagement.
Script: 
python scripts/ga4_report.py --property <id> --json
Reference: 
references/ga4-data-api.md
Default: 28 days, filtered to Organic Search channel group.
自然流量报告：每日会话数、用户数、页面浏览量、跳出率、互动数据。
脚本： 
python scripts/ga4_report.py --property <id> --json
参考文档： 
references/ga4-data-api.md
默认设置： 28天周期，过滤自然搜索渠道组。

/seo google ga4-pages [property-id]

/seo google ga4-pages [property-id]

Top organic landing pages ranked by sessions.
Script: 
python scripts/ga4_report.py --property <id> --report top-pages --json
按会话数排序的热门自然流量着陆页。
脚本： 
python scripts/ga4_report.py --property <id> --report top-pages --json

YouTube (Video SEO)

YouTube（视频SEO）

YouTube mentions have the strongest AI visibility correlation (0.737). Free, API key only.
YouTube提及量与AI可见性的相关性最强（0.737），仅需API密钥即可免费使用。

/seo google youtube <query>

/seo google youtube <query>

Search YouTube for videos. Returns title, channel, views, likes, duration.
Script: 
python scripts/youtube_search.py search "<query>" --json
Reference: 
references/youtube-api.md
Quota: 100 units per search (10,000 units/day free).
搜索YouTube视频，返回标题、频道、播放量、点赞数、时长。
脚本： 
python scripts/youtube_search.py search "<query>" --json
参考文档： 
references/youtube-api.md
配额： 每次搜索消耗100单位（每日免费配额10000单位）。

/seo google youtube-video <video_id>

/seo google youtube-video <video_id>

Detailed video info + tags + top 10 comments.
Script: 
python scripts/youtube_search.py video <video_id> --json
Quota: 2 units (video details + comments).
详细视频信息 + 标签 + 前10条热门评论。
脚本： 
python scripts/youtube_search.py video <video_id> --json
配额： 消耗2单位（视频详情 + 评论）。

NLP Content Analysis

NLP内容分析

Google's own entity/sentiment analysis. Enhances E-E-A-T scoring.
Google官方实体/情感分析，可增强E-E-A-T评分。

/seo google nlp <url-or-text>

/seo google nlp <url-or-text>

Full NLP analysis: entities, sentiment, content classification.
Script: 
python scripts/nlp_analyze.py --url <url> --json
or 
--text "..."
Reference: 
references/nlp-api.md
Free tier: 5,000 units/month. Requires billing enabled on GCP project.
完整NLP分析：实体提取、情感分析、内容分类。
脚本： 
python scripts/nlp_analyze.py --url <url> --json
或 
--text "..."
参考文档： 
references/nlp-api.md
免费额度： 每月5000单位，需在GCP项目中启用计费。

/seo google entities <url-or-text>

/seo google entities <url-or-text>

Entity extraction only (faster, less quota).
Script: 
python scripts/nlp_analyze.py --url <url> --features entities --json
仅实体提取（速度更快，消耗配额更少）。
脚本： 
python scripts/nlp_analyze.py --url <url> --features entities --json

Keyword Research (Google Ads)

关键词研究（Google Ads）

Gold-standard keyword volume data. Requires Google Ads account.
黄金标准的关键词搜索量数据，需Google Ads账号。

/seo google keywords <seed>

/seo google keywords <seed>

Generate keyword ideas from seed terms.
Script: 
python scripts/keyword_planner.py ideas "<seed>" --json
Reference: 
references/keyword-planner-api.md
Requires: Ads developer token + customer ID in config (Tier 3).
基于种子词生成关键词创意。
脚本： 
python scripts/keyword_planner.py ideas "<seed>" --json
参考文档： 
references/keyword-planner-api.md
要求： 配置文件中需包含Ads开发者令牌 + 客户ID（权限等级3）。

/seo google volume <keywords>

/seo google volume <keywords>

Search volume for specific keywords (comma-separated).
Script: 
python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json
查询指定关键词的搜索量（逗号分隔）。
脚本： 
python scripts/keyword_planner.py volume "<kw1>,<kw2>" --json

Supplementary

补充功能

/seo google entity <query>

/seo google entity <query>

Knowledge Graph entity check. Verifies brand presence.
Reference: 
references/supplementary-apis.md
Uses Knowledge Graph Search API with API key.
知识图谱实体校验，验证品牌存在感。
参考文档： 
references/supplementary-apis.md
使用带API密钥的知识图谱搜索API。

/seo google safety <url>

/seo google safety <url>

Web Risk API check for malware/social engineering flags.
Reference: 
references/supplementary-apis.md
Web Risk API检测，排查恶意软件/社会工程学标记。
参考文档： 
references/supplementary-apis.md

/seo google quotas

/seo google quotas

Display rate limits table. Read 
references/rate-limits-quotas.md
.
显示调用限制表，请查看
references/rate-limits-quotas.md
。

Reports

报告生成

After any analysis command, offer to generate a PDF/HTML report.
完成任何分析命令后，可提供生成PDF/HTML报告的选项。

/seo google report <type>

/seo google report <type>

Generate a professional PDF report with charts and analytics.
Script: 
python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf
TypeInputOutput
cwv-audit
PSI + CrUX + CrUX History dataCore Web Vitals audit with gauges, timelines, distributions
gsc-performance
GSC query dataSearch Console report with query tables, quick wins
indexation
Batch inspection dataIndexation status with coverage donut chart
full
All data combinedComprehensive Google SEO report (all sections)
Workflow:
  1. Run data collection commands (pagespeed, gsc, inspect-batch, etc.)
  2. Save JSON output to file: 
    python scripts/pagespeed_check.py <url> --json > data.json
  3. Generate report: 
    python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>
Convention: After completing analysis, suggest: "Generate a report? Use 
/seo google report <type>
"
生成包含图表和分析内容的专业PDF报告。
脚本： 
python scripts/google_report.py --type <type> --data <json> --domain <domain> --format pdf
报告类型输入数据输出内容
cwv-audit
PSI + CrUX + CrUX历史数据Core Web Vitals审计报告，包含仪表盘、时间线、数据分布
gsc-performance
GSC查询数据Search Console报告，包含查询词表格、快速优化机会
indexation
批量检测数据收录状态报告，包含覆盖情况环形图
full
所有数据整合全面的Google SEO报告（包含所有板块）
工作流程：
  1. 运行数据收集命令（pagespeed、gsc、inspect-batch等）
  2. 将JSON输出保存至文件：
    python scripts/pagespeed_check.py <url> --json > data.json
  3. 生成报告：
    python scripts/google_report.py --type cwv-audit --data data.json --domain <domain>
操作规范： 完成分析后，建议用户："需要生成报告吗？请使用
/seo google report <type>
"

Rate Limits

调用限制

APIPer-MinutePer-DayAuth
PSI v5240 QPM25,000 QPDAPI Key
CrUX + History150 QPM (shared)UnlimitedAPI Key
GSC Search Analytics1,200 QPM/site30M QPDService Account
GSC URL Inspection600 QPM2,000 QPD/siteService Account
Indexing API380 RPM200 publish/dayService Account
GA4 Data API10 concurrent~25K tokens/dayService Account
API每分钟限制每日限制认证方式
PSI v5240次/分钟25000次/天API密钥
CrUX + 历史数据150次/分钟（共享）无限制API密钥
GSC搜索分析1200次/分钟/站点3000万次/天服务账号
GSC URL检测600次/分钟2000次/天/站点服务账号
Indexing API380次/分钟200条发布请求/天服务账号
GA4数据API10个并发请求约25000令牌/天服务账号

Cross-Skill Integration

跨技能集成

  • seo-audit: Spawns 
    seo-google
    agent for live CWV + indexation data (conditional)
  • seo-technical: Uses pagespeed_check.py for real CWV field data
  • seo-performance: CrUX field data supplements Lighthouse lab data
  • seo-sitemap: GSC sitemap status shows real crawl/index coverage
  • seo-content: GSC query data informs keyword targeting
  • seo-geo: GSC search appearance data includes AI Overview references
  • seo-audit：在需要时调用
    seo-google
    代理获取实时Core Web Vitals + 收录状态数据
  • seo-technical：使用pagespeed_check.py获取真实Core Web Vitals用户数据
  • seo-performance：CrUX真实用户数据补充Lighthouse实验室数据
  • seo-sitemap：GSC站点地图状态展示真实抓取/收录覆盖情况
  • seo-content：GSC查询数据为关键词定位提供参考
  • seo-geo：GSC搜索展示数据包含AI概览参考

Output Format

输出格式

  • CWV metrics: traffic-light rating (Good / Needs Improvement / Poor)
  • Performance reports: tables with sortable columns
  • Always include data freshness note
  • Save reports as 
    GOOGLE-API-REPORT-{domain}.md
  • Use templates from 
    assets/templates/
    for structured output
  • Core Web Vitals指标：采用交通灯评级（良好/需要改进/较差）
  • 性能报告：包含可排序列的表格
  • 务必标注数据新鲜度说明
  • 报告保存为
    GOOGLE-API-REPORT-{domain}.md
  • 使用
    assets/templates/
    中的模板生成结构化输出

Technical Notes

技术说明

  • INP replaced FID on March 12, 2024. Never reference FID.
  • CLS values from CrUX are string-encoded (e.g., "0.05"). Scripts handle parsing.
  • CrUX 404 = insufficient traffic, not an auth error.
  • Search Analytics data has 2-3 day lag.
  • round_trip_time
    replaced 
    effectiveConnectionType
    in CrUX (Feb 2025).
  • Custom Search JSON API is closed to new customers (2025).
  • INP已于2024年3月12日替代FID，请勿再引用FID。
  • CrUX返回的CLS值为字符串格式（例如"0.05"），脚本会自动处理解析。
  • CrUX返回404表示流量不足，并非认证错误。
  • 搜索分析数据存在2-3天的延迟。
  • CrUX中的
    round_trip_time
    已于2025年2月替代
    effectiveConnectionType
    。
  • 自定义搜索JSON API自2025年起不再对新用户开放。

Error Handling

错误处理

ScenarioAction
No credentials configuredRun 
/seo google setup
. List Tier 0 commands that work with just an API key.
Service account lacks GSC accessReport error. Instruct: add 
client_email
to GSC > Settings > Users > Add.
CrUX data unavailable (404)Report insufficient Chrome traffic. Suggest PSI lab data as fallback.
GA4 property not foundReport error. Show how to find property ID in GA4 Admin > Property Details.
Indexing API quota exceededReport 200/day limit. Suggest prioritizing most important URLs.
Rate limit (429)Wait and retry with exponential backoff. Report which API hit the limit.
场景处理方式
未配置凭据运行
/seo google setup
，告知用户仅需API密钥即可使用的等级0命令。
服务账号无GSC访问权限报告错误，指导用户：将
client_email
添加至GSC > 设置 > 用户 > 添加。
CrUX数据不可用（404）报告流量不足，建议使用PSI实验室数据作为替代。
未找到GA4属性报告错误，告知用户在GA4管理后台 > 属性详情中查找属性ID。
Indexing API配额耗尽告知每日200条的限制，建议优先提交最重要的URL。
调用限制触发（429）等待后使用指数退避策略重试，告知用户哪个API触发了限制。