Back to Details

google-search-console

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Google Search Console Skill

Google Search Console Skill

Created by Return Zero Inc.
Comprehensive Google Search Console API skill for Claude Code providing search analytics, URL inspection, sitemap management, and site verification capabilities.
由Return Zero Inc.创建
为Claude Code打造的全面Google Search Console API技能，提供搜索分析、URL检查、站点地图管理和站点验证功能。

When to Use

使用场景

  • User mentions "Google Search Console", "GSC", "search console"
  • User asks about search performance, clicks, impressions, CTR
  • User needs URL indexing status or inspection
  • User wants to manage sitemaps
  • User asks about search rankings or index status
  • User needs SEO analytics data from Google
  • 用户提及"Google Search Console"、"GSC"、"search console"
  • 用户询问搜索性能、点击量、展示量、点击率（CTR）
  • 用户需要查询URL索引状态或进行URL检查
  • 用户想要管理站点地图
  • 用户询问搜索排名或索引状态
  • 用户需要从Google获取SEO分析数据

Features

功能特性

1. Search Analytics ⭐

1. 搜索分析 ⭐

  • Query search performance data (clicks, impressions, CTR, position)
  • Filter by date range, page, query, country, device
  • Group by dimensions (query, page, country, device, date)
  • Compare time periods
  • Export to CSV/JSON
  • 查询搜索性能数据（点击量、展示量、点击率、排名）
  • 按日期范围、页面、查询词、国家、设备筛选
  • 按维度分组（查询词、页面、国家、设备、日期）
  • 对比不同时间段数据
  • 导出为CSV/JSON格式

2. URL Inspection

2. URL检查

  • Check indexing status of specific URLs
  • View crawl information
  • Check mobile usability
  • Identify indexing issues
  • Request indexing for URLs
  • 检查特定URL的索引状态
  • 查看抓取信息
  • 检查移动端可用性
  • 识别索引问题
  • 提交URL索引请求

3. Sitemap Management

3. 站点地图管理

  • List all sitemaps for a site
  • Submit new sitemaps
  • Delete sitemaps
  • Check sitemap status and errors
  • 列出站点的所有站点地图
  • 提交新的站点地图
  • 删除站点地图
  • 检查站点地图状态和错误

4. Site Management

4. 站点管理

  • List all verified sites
  • Add new sites
  • Remove sites
  • Check verification status
  • 列出所有已验证的站点
  • 添加新站点
  • 删除站点
  • 检查验证状态

Environment Variables

环境变量

This skill uses environment variables managed by 
jelly-dotenv
. See 
skills/jelly-dotenv/SKILL.md
for configuration details.
本技能使用
jelly-dotenv
管理的环境变量。配置详情请查看
skills/jelly-dotenv/SKILL.md
。

Option 1: Service Account (Recommended)

选项1：服务账号（推荐）

bash
undefined
bash
undefined

Service account JSON key file path

Service account JSON key file path

GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

Or inline JSON (for CI/CD environments)

Or inline JSON (for CI/CD environments)

GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'
undefined
GOOGLE_SERVICE_ACCOUNT_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'
undefined

Option 2: OAuth 2.0 Client Credentials

选项2：OAuth 2.0客户端凭证

bash
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token
bash
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REFRESH_TOKEN=your-refresh-token

Common Settings

通用设置

bash
undefined
bash
undefined

Default site URL (optional, can be specified per request)

Default site URL (optional, can be specified per request)

GOOGLE_SEARCH_CONSOLE_SITE_URL=https://your-site.com
GOOGLE_SEARCH_CONSOLE_SITE_URL=https://your-site.com

Alternative naming patterns (auto-detected)

Alternative naming patterns (auto-detected)

GSC_SITE_URL=https://your-site.com SEARCH_CONSOLE_SITE=sc-domain:your-site.com

Variables can be configured in either:
- `skills/jelly-dotenv/.env` (skill-common, highest priority)
- Project root `/.env` (project-specific, fallback)
GSC_SITE_URL=https://your-site.com SEARCH_CONSOLE_SITE=sc-domain:your-site.com

变量可在以下位置配置：
- `skills/jelly-dotenv/.env`（技能通用配置，优先级最高）
- 项目根目录`/.env`（项目特定配置，备选）

Configuration

配置步骤

Setting Up Service Account

配置服务账号

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable "Google Search Console API"
  4. Create a Service Account:
    • Go to IAM & Admin → Service Accounts
    • Create service account
    • Download JSON key file
  5. Add service account email to Search Console:
    • Go to Search Console
    • Settings → Users and permissions
    • Add user with service account email
    • Grant "Full" or "Restricted" access
  1. 访问Google Cloud Console
  2. 创建新项目或选择现有项目
  3. 启用"Google Search Console API"
  4. 创建服务账号：
    • 进入IAM与管理 → 服务账号
    • 创建服务账号
    • 下载JSON密钥文件
  5. 将服务账号邮箱添加至Search Console：
    • 访问Search Console
    • 设置 → 用户与权限
    • 添加服务账号邮箱为用户
    • 授予"完全权限"或"受限权限"

Setting Up OAuth 2.0

配置OAuth 2.0

  1. Go to Google Cloud Console
  2. Create OAuth 2.0 credentials (Web application)
  3. Set authorized redirect URI
  4. Use OAuth playground or your app to get refresh token
  5. Required scope: 
    https://www.googleapis.com/auth/webmasters.readonly
  1. 访问Google Cloud Console
  2. 创建OAuth 2.0凭证（Web应用）
  3. 设置授权重定向URI
  4. 使用OAuth playground或你的应用获取刷新令牌
  5. 所需权限范围：
    https://www.googleapis.com/auth/webmasters.readonly

Usage Scenarios

使用场景示例

Scenario 1: Search Performance Overview

场景1：搜索性能概览

User Request: "Show me search performance for the last 7 days"
Skill Actions:
  1. Load credentials from environment
  2. Query Search Analytics API with date range
  3. Aggregate clicks, impressions, CTR, position
  4. Format as Markdown table with trends
Output:
markdown
undefined
用户请求："Show me search performance for the last 7 days"
技能操作：
  1. 从环境变量加载凭证
  2. 按日期范围查询搜索分析API
  3. 汇总点击量、展示量、点击率、排名数据
  4. 格式化为带趋势的Markdown表格
输出结果：
markdown
undefined

Search Performance (Last 7 Days)

Search Performance (Last 7 Days)

MetricValueChange
Clicks1,234+12%
Impressions45,678+8%
CTR2.7%+0.3%
Avg Position15.2-2.1
MetricValueChange
Clicks1,234+12%
Impressions45,678+8%
CTR2.7%+0.3%
Avg Position15.2-2.1

Top Queries

Top Queries

QueryClicksImpressionsCTRPosition
keyword 12345,6784.1%8.5
keyword 21894,3214.4%12.3
undefined
QueryClicksImpressionsCTRPosition
keyword 12345,6784.1%8.5
keyword 21894,3214.4%12.3
undefined

Scenario 2: URL Inspection

场景2：URL检查

User Request: "Check indexing status for https://example.com/page"
Skill Actions:
  1. Call URL Inspection API
  2. Parse indexing result
  3. Check coverage status
  4. Display mobile usability
Output:
markdown
undefined
用户请求："Check indexing status for https://example.com/page"
技能操作：
  1. 调用URL检查API
  2. 解析索引结果
  3. 检查覆盖状态
  4. 展示移动端可用性
输出结果：
markdown
undefined

URL Inspection: https://example.com/page

URL Inspection: https://example.com/page

PropertyStatus
Index Status✅ Indexed
Crawled2024-01-15
Canonicalhttps://example.com/page
Mobile Usability✅ Mobile friendly
Rich Results⚠️ 2 warnings
undefined
PropertyStatus
Index Status✅ Indexed
Crawled2024-01-15
Canonicalhttps://example.com/page
Mobile Usability✅ Mobile friendly
Rich Results⚠️ 2 warnings
undefined

Scenario 3: Sitemap Management

场景3：站点地图管理

User Request: "Show all sitemaps and submit a new one"
Skill Actions:
  1. List existing sitemaps
  2. Show status and last submitted date
  3. Submit new sitemap URL
  4. Confirm submission
用户请求："Show all sitemaps and submit a new one"
技能操作：
  1. 列出现有站点地图
  2. 展示状态和最后提交日期
  3. 提交新的站点地图URL
  4. 确认提交成功

Scenario 4: Top Pages Analysis

场景4：热门页面分析

User Request: "What are my top performing pages?"
Skill Actions:
  1. Query Search Analytics grouped by page
  2. Sort by clicks
  3. Include impressions, CTR, position
  4. Highlight pages with high impressions but low CTR
用户请求："What are my top performing pages?"
技能操作：
  1. 按页面分组查询搜索分析数据
  2. 按点击量排序
  3. 包含展示量、点击率、排名数据
  4. 高亮展示量高但点击率低的页面

API Reference

API参考

Search Analytics Query

搜索分析查询

typescript
interface SearchAnalyticsRequest {
  startDate: string;      // YYYY-MM-DD
  endDate: string;        // YYYY-MM-DD
  dimensions?: ('query' | 'page' | 'country' | 'device' | 'date')[];
  searchType?: 'web' | 'image' | 'video' | 'news';
  dimensionFilterGroups?: FilterGroup[];
  aggregationType?: 'auto' | 'byPage' | 'byProperty';
  rowLimit?: number;      // Max 25000
  startRow?: number;
}
typescript
interface SearchAnalyticsRequest {
  startDate: string;      // YYYY-MM-DD
  endDate: string;        // YYYY-MM-DD
  dimensions?: ('query' | 'page' | 'country' | 'device' | 'date')[];
  searchType?: 'web' | 'image' | 'video' | 'news';
  dimensionFilterGroups?: FilterGroup[];
  aggregationType?: 'auto' | 'byPage' | 'byProperty';
  rowLimit?: number;      // Max 25000
  startRow?: number;
}

URL Inspection

URL检查

typescript
interface UrlInspectionRequest {
  inspectionUrl: string;
  siteUrl: string;
  languageCode?: string;
}
typescript
interface UrlInspectionRequest {
  inspectionUrl: string;
  siteUrl: string;
  languageCode?: string;
}

Sitemap Operations

站点地图操作

OperationMethodEndpoint
ListGET
/webmasters/v3/sites/{siteUrl}/sitemaps
GetGET
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
SubmitPUT
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
DeleteDELETE
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
操作方法端点
列出GET
/webmasters/v3/sites/{siteUrl}/sitemaps
获取GET
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
提交PUT
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}
删除DELETE
/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}

Output Formats

输出格式

Markdown (Default)

Markdown（默认）

  • Formatted tables with metrics
  • Trend indicators (↑↓)
  • Status icons (✅⚠️❌)
  • Summary insights
  • 带指标的格式化表格
  • 趋势指示器（↑↓）
  • 状态图标（✅⚠️❌）
  • 总结洞察

JSON

JSON

  • Raw API response
  • Full data structure
  • Programmatic access
  • 原始API响应
  • 完整数据结构
  • 程序化访问

CSV

CSV

  • Spreadsheet-compatible export
  • All data rows
  • For further analysis
  • 兼容电子表格的导出格式
  • 所有数据行
  • 用于进一步分析

Error Handling

错误处理

Authentication Errors

认证错误

ErrorCauseSolution
401 UnauthorizedInvalid credentialsCheck service account key or OAuth tokens
403 ForbiddenNo access to siteAdd service account to Search Console
Invalid scopeWrong OAuth scopeUse 
webmasters.readonly
scope
错误原因解决方案
401 Unauthorized凭证无效检查服务账号密钥或OAuth令牌
403 Forbidden无站点访问权限将服务账号添加至Search Console
Invalid scopeOAuth权限范围错误使用
webmasters.readonly
权限范围

API Errors

API错误

ErrorCauseSolution
404 Not FoundSite not in Search ConsoleAdd site to Search Console first
400 Bad RequestInvalid parametersCheck date format (YYYY-MM-DD)
429 Rate LimitToo many requestsWait and retry with backoff
错误原因解决方案
404 Not Found站点未在Search Console中先将站点添加至Search Console
400 Bad Request参数无效检查日期格式（YYYY-MM-DD）
429 Rate Limit请求过于频繁等待后重试，使用退避策略

Common Issues

常见问题

"Configuration error: No Google credentials found"
bash
undefined
"Configuration error: No Google credentials found"
bash
undefined

Solution: Add credentials to .env

Solution: Add credentials to .env

GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json

**"Site not found or no access"**
```bash
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/key.json

**"Site not found or no access"**
```bash

Solution: Add service account email to Search Console

Solution: Add service account email to Search Console

Go to: Search Console → Settings → Users and permissions

Go to: Search Console → Settings → Users and permissions


**"Invalid date range"**
```bash

**"Invalid date range"**
```bash

Solution: Use YYYY-MM-DD format, max 16 months historical data

Solution: Use YYYY-MM-DD format, max 16 months historical data

undefined
undefined

Security Policy

安全政策

Authentication

认证机制

  • Service Account: Recommended for server-side usage
  • OAuth 2.0: For user-authenticated requests
  • Credentials: Loaded from environment variables only
  • Logging: Private keys and tokens automatically redacted
  • 服务账号：推荐用于服务器端场景
  • OAuth 2.0：用于用户认证的请求
  • 凭证：仅从环境变量加载
  • 日志：自动脱敏私钥和令牌

Data Access

数据访问

  • Read-Only by Default: Uses 
    webmasters.readonly
    scope
  • Write Operations: Sitemap submit/delete requires full scope
  • Site-Scoped: Access limited to authorized sites only
  • 默认只读：使用
    webmasters.readonly
    权限范围
  • 写入操作：提交/删除站点地图需要完整权限范围
  • 站点级权限：仅能访问已授权的站点

Rate Limiting

请求限制

  • Automatic: Respects Google API quotas
  • Retry: Exponential backoff on 429 errors
  • Daily Quota: 1,200 queries per day (default)
  • 自动遵守：遵循Google API配额限制
  • 重试机制：遇到429错误时使用指数退避重试
  • 每日配额：默认每日1200次查询

Limitations

限制说明

  • Historical Data: Maximum 16 months of search data
  • Data Freshness: 2-3 day delay for search analytics
  • URL Inspection: 2,000 requests per day per site
  • Row Limit: Maximum 25,000 rows per query
  • Dimensions: Maximum 3 dimensions per query
  • 历史数据：最多可查询16个月的搜索数据
  • 数据新鲜度：搜索分析数据存在2-3天延迟
  • URL检查：每个站点每日最多2000次请求
  • 行数限制：每次查询最多返回25000行数据
  • 维度限制：每次查询最多使用3个维度

Integration with Claude Code

与Claude Code的集成

This skill activates automatically when users mention:
  • "google search console", "gsc", "search console"
  • "search performance", "search analytics"
  • "url inspection", "index status"
  • "sitemap", "sitemap management"
  • "seo analytics", "seo data"
The skill will:
  1. Load Google credentials from .env
  2. Execute the requested query/operation
  3. Format results as Markdown tables
  4. Provide actionable insights and recommendations
当用户提及以下内容时，本技能将自动激活：
  • "google search console"、"gsc"、"search console"
  • "search performance"、"search analytics"
  • "url inspection"、"index status"
  • "sitemap"、"sitemap management"
  • "seo analytics"、"seo data"
技能将执行以下操作：
  1. 从.env文件加载Google凭证
  2. 执行用户请求的查询/操作
  3. 将结果格式化为Markdown表格
  4. 提供可操作的洞察和建议

References

参考资料