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 Query Language）を使用します。

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_ERROR	GAQL の構文エラー
QUOTA_ERROR	API クォータ超過

GAQL でよくある間違い

• WHERE segments.date DURING ... がない（ほとんどの指標クエリで必要）
• REMOVED ステータスフィルターを誤って使用する
• costMicros を 1,000,000 で割る処理を忘れる
• 互換性のないリソースとセグメントの組み合わせをリクエストする

ヒント

• 必ず REMOVED のキャンペーン、広告グループ、キーワードを除外してください
• 大量の結果を取得する場合は、search ではなく searchStream を使用してください（ページネーションは不要です）
• 複数セクションのレポートを作成する場合は、結果をキャッシュしてください
• 品質スコアが 0 の場合は「データ不足」を意味します。null として扱ってください