介绍
# Google Search Console
使用托管的 OAuth 身份验证访问 Google Search Console API。查询搜索分析数据、管理站点地图并监控网站在 Google 搜索中的表现。
## 快速开始
```bash # List sites python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-search-console/webmasters/v3/sites') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/google-search-console/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Google Search Console API 端点路径。网关会将请求代理到 `www.googleapis.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 请求头中提供 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Google OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-search-console&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-search-console'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-search-console", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Google Search Console 连接，请使用 `Maton-Connection` 请求头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-search-console/webmasters/v3/sites') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活跃连接。
## API 参考
### 站点
```bash GET /google-search-console/webmasters/v3/sites GET /google-search-console/webmasters/v3/sites/{siteUrl} ```
注意：站点 URL 必须进行 URL 编码（例如，`https%3A%2F%2Fexample.com%2F`）
### 搜索分析
```bash POST /google-search-console/webmasters/v3/sites/{siteUrl}/searchAnalytics/query Content-Type: application/json
{ "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["query"], "rowLimit": 100 } ```
### 站点地图
```bash GET /google-search-console/webmasters/v3/sites/{siteUrl}/sitemaps PUT /google-search-console/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath} DELETE /google-search-console/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath} ```
## 搜索分析示例
### 热门查询
```json { "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["query"], "rowLimit": 25 } ```
### 热门页面
```json { "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["page"], "rowLimit": 25 } ```
### 设备分布
```json { "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["device"], "rowLimit": 10 } ```
### 每日表现
```json { "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["date"], "rowLimit": 31 } ```
### 筛选查询
```json { "startDate": "2024-01-01", "endDate": "2024-01-31", "dimensions": ["query"], "dimensionFilterGroups": [{ "filters": [{ "dimension": "query", "operator": "contains", "expression": "keyword" }] }], "rowLimit": 100 } ```
## 维度
- `query` - 搜索查询 - `page` - 页面 URL - `country` - 国家/地区代码 - `device` - DESKTOP, MOBILE, TABLET - `date` - 日期
## 指标（自动返回）
- `clicks` - 点击次数 - `impressions` - 展示次数 - `ctr` - 点击率 - `position` - 平均排名
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/google-search-console/webmasters/v3/sites/https%3A%2F%2Fexample.com/searchAnalytics/query', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.MATON_API_KEY}` }, body: JSON.stringify({ startDate: '2024-01-01', endDate: '2024-01-31', dimensions: ['query'], rowLimit: 25 }) } ); ```
### Python
```python import os import requests from urllib.parse import quote
site_url = quote('https://example.com', safe='') response = requests.post( f'https://gateway.maton.ai/google-search-console/webmasters/v3/sites/{site_url}/searchAnalytics/query', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={ 'startDate': '2024-01-01', 'endDate': '2024-01-31', 'dimensions': ['query'], 'rowLimit': 25 } ) ```
## 注意事项
- 站点 URL 在路径中必须进行 URL 编码 - 日期范围限制为 16 个月 - 每个请求最多返回 25,000 行 - 使用 `startRow` 进行分页 - 数据有 2-3 天的延迟 - 重要：使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，`$MATON_API_KEY` 等环境变量在某些 shell 环境中可能无法正确展开。您可能会在通过管道传输时遇到“Invalid API key”（无效的 API 密钥）错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Search Console 连接 | | 401 | Maton API 密钥无效或缺失 | | 429 | 速率受限（每个账户每秒 10 次请求）| | 4xx/5xx | 来自 Search Console API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `google-search-console` 开头。例如：
- 正确：`https://gateway.maton.ai/google-search-console/webmasters/v3/sites` - 错误：`https://gateway.maton.ai/webmasters/v3/sites`
## 资源
- [Search Console API 参考](https://developers.google.com/webmaster-tools/v1/api_reference_index) - [列出站点](https://developers.google.com/webmaster-tools/v1/sites/list) - [搜索分析](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) - [站点地图](https://developers.google.com/webmaster-tools/v1/sitemaps) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])