mcpField
G
google-ads-report

google-ads-report

github.com/openclaudia营销与增长722482 次安装1 周前更新
代码仓库

关于 google-ads-report

通过 Google Ads API 获取广告系列、关键词、广告组、搜索词、转化和支出数据的技能。它提供 GAQL 查询示例及月度效果报告的整理流程。

主要功能

  1. 01广告系列和广告组报告
  2. 02关键词与 Quality Score 分析
  3. 03搜索词和否定关键词审查
  4. 04转化与 ROAS 分析
  5. 05每日支出趋势查询
  6. 06月度报告流程与格式

适用场景

  1. 01编制月度 Google Ads 报告
  2. 02比较广告系列和关键词效果
  3. 03查找应添加或排除的搜索词
  4. 04审查转化价值和 ROAS

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/openclaudia/openclaudia-skills --skill google-ads-report

安装后在 Claude Code 中输入/google-ads-report确认已加载。

详细介绍

Google Ads 报告

从 Google Ads API 拉取广告系列、关键字和转化数据。

前置条件

需要：

  • GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET（OAuth）
  • GOOGLE_ADS_DEVELOPER_TOKEN（在 https://ads.google.com/home/tools/manager-accounts/ 申请）
  • GOOGLE_ADS_CUSTOMER_ID（账号 ID，格式为 XXX-XXX-XXXX，传入时不带连字符）
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID（如果使用经理账号，则为经理账号 ID）

在 .env、.env.local 或 ~/.claude/.env.global 中设置。

获取访问令牌
# Same OAuth flow as other Google APIs
# Scope needed: https://www.googleapis.com/auth/adwords

echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/adwords&response_type=code&access_type=offline"

# Exchange code for tokens
curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d "code={AUTH_CODE}" \
  -d "client_id=${GOOGLE_CLIENT_ID}" \
  -d "client_secret=${GOOGLE_CLIENT_SECRET}" \
  -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -d "grant_type=authorization_code"

API 基础地址

Google Ads API 通过 REST 使用 GAQL（Google Ads 查询语言）。

POST https://googleads.googleapis.com/v17/customers/{CUSTOMER_ID}/googleAds:searchStream

请求头：

Authorization: Bearer {ACCESS_TOKEN}
developer-token: {DEVELOPER_TOKEN}
login-customer-id: {LOGIN_CUSTOMER_ID}  # Only if using manager account
Content-Type: application/json

1. 广告系列效果报告

查看所有广告系列的概况及关键指标。

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions, metrics.cost_per_conversion, metrics.conversions_value FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status != REMOVED ORDER BY metrics.cost_micros DESC"
  }'
解析广告系列数据
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"{'Campaign':<35} {'Status':<10} {'Impr':>8} {'Clicks':>7} {'CTR':>7} {'Avg CPC':>8} {'Cost':>10} {'Conv':>6} {'CPA':>8}\")
print('-' * 110)
for batch in data:
    for row in batch.get('results', []):
        c = row.get('campaign', {})
        m = row.get('metrics', {})
        cost = int(m.get('costMicros', 0)) / 1_000_000
        cpc = int(m.get('averageCpc', 0)) / 1_000_000
        cpa = float(m.get('costPerConversion', 0)) / 1_000_000 if m.get('costPerConversion') else 0
        print(f\"{c.get('name',''):<35} {c.get('status',''):<10} {int(m.get('impressions',0)):>8} {int(m.get('clicks',0)):>7} {float(m.get('ctr',0))*100:>6.2f}% \${cpc:>7.2f} \${cost:>9.2f} {float(m.get('conversions',0)):>6.1f} \${cpa:>7.2f}\")
"
重要提示：微单位费用

Google Ads API 中的所有费用值都以微单位表示（货币单位的 1/1,000,000）。除以 1,000,000 即可得到实际金额。

2. 关键字效果报告

查看各个关键字的效果。

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM keyword_view WHERE segments.date DURING LAST_30_DAYS AND ad_group_criterion.status != REMOVED ORDER BY metrics.cost_micros DESC LIMIT 50"
  }'
质量得分明细
curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score, ad_group_criterion.quality_info.post_click_quality_score, ad_group_criterion.quality_info.search_predicted_ctr, metrics.impressions, metrics.average_cpc FROM keyword_view WHERE ad_group_criterion.quality_info.quality_score IS NOT NULL AND segments.date DURING LAST_30_DAYS ORDER BY ad_group_criterion.quality_info.quality_score ASC LIMIT 50"
  }'

质量得分组成部分：

  • quality_score：总体得分（1-10）
  • creative_quality_score：广告相关性（BELOW_AVERAGE、AVERAGE、ABOVE_AVERAGE）
  • post_click_quality_score：着陆页体验
  • search_predicted_ctr：预期点击率

3. 广告组效果

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.name, ad_group.name, ad_group.status, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions FROM ad_group WHERE segments.date DURING LAST_30_DAYS AND ad_group.status != REMOVED ORDER BY metrics.cost_micros DESC LIMIT 50"
  }'

4. 搜索字词报告

查看用户实际搜索的内容（与您的关键字对比）。

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT search_term_view.search_term, segments.keyword.info.text, segments.keyword.info.match_type, metrics.impressions, metrics.clicks, metrics.ctr, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 100"
  }'

可用于：

  • 发现新的关键字机会（转化率高的搜索字词）
  • 找出否定关键字候选项（产生费用的不相关字词）
  • 发现匹配类型问题（广泛匹配带来无效流量）

5. 转化跟踪

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT campaign.name, metrics.conversions, metrics.conversions_value, metrics.cost_micros, metrics.conversions_from_interactions_rate, metrics.value_per_conversion FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status = ENABLED ORDER BY metrics.conversions DESC"
  }'
ROAS 计算
# ROAS = conversions_value / (cost_micros / 1_000_000)
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"{'Campaign':<35} {'Cost':>10} {'Conv Value':>12} {'ROAS':>8}\")
for batch in data:
    for row in batch.get('results', []):
        c = row['campaign']['name']
        m = row['metrics']
        cost = int(m.get('costMicros', 0)) / 1_000_000
        value = float(m.get('conversionsValue', 0))
        roas = value / cost if cost > 0 else 0
        print(f\"{c:<35} \${cost:>9.2f} \${value:>11.2f} {roas:>7.2f}x\")
"

6. 每日支出趋势

curl -s -X POST \
  "https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
  -H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
  -H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT segments.date, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM customer WHERE segments.date DURING LAST_30_DAYS ORDER BY segments.date DESC"
  }'

GAQL 日期范围

在 GAQL 中使用以下内置日期范围：

  • TODAY、YESTERDAY
  • LAST_7_DAYS、LAST_14_DAYS、LAST_30_DAYS
  • THIS_MONTH、LAST_MONTH
  • THIS_QUARTER、LAST_QUARTER
  • 自定义：segments.date BETWEEN '2024-01-01' AND '2024-03-31'

工作流：Google Ads 月度报告

收到完整广告报告的请求时：

  1. 账号概览：总支出、展示次数、点击次数、转化次数、ROAS
  2. 广告系列效果：所有有效广告系列，按支出排名
  3. 热门关键字：按支出排名前 20 的关键字及质量得分
  4. 搜索字词：热门搜索字词和否定关键字候选项
  5. 质量得分分布：各 QS 等级的关键字数量
  6. 转化分析：按广告系列统计转化次数和 ROAS
  7. 每日趋势：期间内的支出和转化趋势
报告格式
## Google Ads Report: {Account Name}
### Period: {date range}

### Account Summary
| Metric | Value | vs Previous |
|--------|-------|-------------|
| Total Spend | $X | +Y% |
| Impressions | X | +Y% |
| Clicks | X | +Y% |
| CTR | X% | +Y pp |
| Avg CPC | $X | +Y% |
| Conversions | X | +Y% |
| ROAS | Xx | +Y% |

### Campaign Performance
| Campaign | Spend | Clicks | Conv | CPA | ROAS |
|----------|-------|--------|------|-----|------|
| ...      | ...   | ...    | ...  | ... | ...  |

### Top Keywords (by spend)
| Keyword | Match | QS | Spend | Clicks | Conv | CPC |
|---------|-------|-----|-------|--------|------|-----|
| ...     | ...   | ... | ...   | ...    | ...  | ... |

### Recommendations
- **Pause**: Keywords with high spend and zero conversions
- **Increase Bids**: Keywords with high conversion rate but limited budget
- **Negative Keywords**: Search terms wasting budget
- **Quality Score Fixes**: Keywords with QS < 5 and actions to improve
- **Budget Reallocation**: Shift budget from low-ROAS to high-ROAS campaigns

错误处理

错误原因
AUTHENTICATION_ERROR访问令牌无效或已过期
AUTHORIZATION_ERROR开发者令牌问题或账号访问问题
REQUEST_ERRORGAQL 语法错误
QUOTA_ERRORAPI 配额已超限
常见 GAQL 错误
  • 缺少 WHERE segments.date DURING ...（大多数指标查询都需要）
  • 错误使用 REMOVED 状态筛选条件
  • 忘记将 costMicros 除以 1,000,000
  • 请求不兼容的资源与细分组合

提示

  • 始终筛除已移除的广告系列、广告组和关键字
  • 大型结果集使用 searchStream 而不是 search（无需分页）
  • 构建多部分报告时缓存结果
  • 质量得分为 0 表示“数据不足”，应视为 null

评论

支持 Markdown