google-ads-open-cli

Google Ads CLI スキル

Google Ads API（v23）用の読み取り専用 CLI である google-ads-open-cli を利用できます。広告アカウントの照会、パフォーマンス統計の取得、カスタム GAQL クエリの実行に使用します。

クイックスタート

# Check if the CLI is available
google-ads-open-cli --help

# List accessible accounts
google-ads-open-cli customers

CLI がインストールされていない場合は、インストールしてください。

npm install -g google-ads-open-cli

認証

この CLI は OAuth2 ユーザー認証情報を使用します（Google Ads API はサービスアカウントをサポートしていません）。認証情報は ~/.config/google-ads-open-cli/credentials.json に保存されます。

コマンドを実行する前に、google-ads-open-cli customers を実行して、認証情報が設定されていることを確認してください。認証情報エラーが発生した場合は、ユーザーに認証を設定するよう依頼してください。

google-ads-open-cli auth login \
  --developer-token=xxx \
  --client-id=xxx \
  --client-secret=xxx

値の取得方法：

1. developer_token：Google Ads のマネージャーアカウントにログインし、API センターを開きます。developer token をコピーします。
2. client_id と client_secret：Google Cloud Console > 認証情報に移動し、OAuth クライアント ID（デスクトップアプリの種類）を作成します。Google Ads API が有効になっていることを確認してください。

認証のためにブラウザーが開きます。ユーザーが、使用する Google Ads データにアクセスできる Google アカウントでログインしていることを確認してください。承認後、認証情報は自動的に保存されます。それ以降のコマンドでは、トークンが自動更新されます。

MCC（マネージャー）アカウントの場合は、認証情報ファイルに "login_customer_id": "1234567890" を追加してください。

別の方法として、GOOGLE_ADS_ACCESS_TOKEN と GOOGLE_ADS_DEVELOPER_TOKEN 環境変数を設定できます（CI/CD で便利です）。

エンティティ階層

Manager Account (MCC)
 └── Customer Account (10-digit ID, e.g. 1234567890)
      ├── Campaign
      │    └── Ad Group
      │         ├── Ad (Ad Group Ad)
      │         └── Keyword (Ad Group Criterion)
      ├── Campaign Budget
      ├── Conversion Action
      ├── User List (remarketing)
      └── Asset (images, videos, sitelinks)

顧客 ID は 10 桁の数字です。ハイフンは自動的に削除されます。

金額

Google Ads ではマイクロ単位を使用します。通貨単位 1 は 1,000,000 マイクロ単位に相当します。CLI が返す費用、入札額、予算の値はすべてマイクロ単位です。金額をユーザーに提示するときは、必ず 1,000,000 で割ってください。

出力形式

すべてのコマンドは、デフォルトで整形済みの JSON を出力します。1 行の JSON（パイプ処理に便利です）を出力するには、--format compact を使用してください。

組み込みコマンド

アカウントの検索

# List all accessible accounts
google-ads-open-cli customers

# Get details for a specific account
google-ads-open-cli customer 1234567890

# List sub-accounts under an MCC
google-ads-open-cli account-hierarchy 1234567890

エンティティの参照

# Campaigns (filter by status: ENABLED, PAUSED, REMOVED)
google-ads-open-cli campaigns 1234567890
google-ads-open-cli campaigns 1234567890 --status ENABLED

# Get a specific campaign
google-ads-open-cli campaign 1234567890 98765

# Campaign budgets
google-ads-open-cli campaign-budgets 1234567890

# Ad groups (filter by campaign, status)
google-ads-open-cli ad-groups 1234567890 --campaign 98765

# Get a specific ad group
google-ads-open-cli ad-group 1234567890 11111

# Ads (filter by campaign, ad group, status)
google-ads-open-cli ads 1234567890 --campaign 98765 --ad-group 11111

# Get a specific ad (requires ad-group-id and ad-id)
google-ads-open-cli ad 1234567890 11111 22222

# Keywords
google-ads-open-cli keywords 1234567890 --campaign 98765 --status ENABLED

すべての一覧表示コマンドは --limit <n> をサポートしています（デフォルトは 100 です）。

パフォーマンス統計

統計コマンドでは、--start と --end の日付（YYYY-MM-DD）が必要です。返される行数は最大 --limit 行（デフォルトは 1000 行）で、日付の新しい順です（keyword-stats はインプレッション数の多い順です）。標準エラー出力に切り捨てを示す {"warning": ...} が含まれている場合は、合計を計算する前に --limit を増やすか、日付範囲を絞り込んでください。

# Campaign stats
google-ads-open-cli campaign-stats 1234567890 --start 2026-01-01 --end 2026-01-31

# Campaign stats with device segment
google-ads-open-cli campaign-stats 1234567890 --start 2026-01-01 --end 2026-01-31 --segments device

# Ad group stats (filter by --campaign and/or --ad-group)
google-ads-open-cli ad-group-stats 1234567890 --start 2026-01-01 --end 2026-01-31 --campaign 98765

# Ad-level stats (filter by --campaign and/or --ad-group)
google-ads-open-cli ad-stats 1234567890 --start 2026-01-01 --end 2026-01-31

# Keyword stats (sorted by impressions desc; filter by --campaign and/or --ad-group)
google-ads-open-cli keyword-stats 1234567890 --start 2026-01-01 --end 2026-01-31

campaign-stats --segments で使用できるセグメントは device、ad_network_type、day_of_week です（カンマ区切り）。

統計コマンドのデフォルトの --limit は 1000 です。

その他のコマンド

# Audiences and remarketing lists
google-ads-open-cli audiences 1234567890
google-ads-open-cli user-lists 1234567890

# Assets and extensions
google-ads-open-cli assets 1234567890 --type SITELINK
google-ads-open-cli extensions 1234567890 --campaign 98765

# Conversions and billing
google-ads-open-cli conversion-actions 1234567890
google-ads-open-cli billing 1234567890

# Change history (default last 14 days, --days max 90)
google-ads-open-cli change-status 1234567890 --days 30 --limit 20

# Negative keyword lists
google-ads-open-cli negative-keywords 1234567890

アセットの種類：IMAGE、MEDIA_BUNDLE、TEXT、YOUTUBE_VIDEO、LEAD_FORM、CALL、CALLOUT、SITELINK、STRUCTURED_SNIPPET。

カスタム GAQL クエリ

query コマンドは、組み込みコマンドで対応できない操作に使用します。Google Ads API に対して任意の GAQL（Google Ads Query Language）を実行します。

google-ads-open-cli query <customer-id> "<GAQL>"

GAQL 構文

SELECT field1, field2, ...
FROM resource_name
WHERE conditions
ORDER BY field [ASC|DESC]
LIMIT count
PARAMETERS key=value

• SELECT と FROM は必須です。WHERE、ORDER BY、LIMIT、PARAMETERS は省略可能です。
• キーワード（SELECT、FROM、WHERE など）は大文字と小文字を区別しません。
• フィールド名、リソース名、列挙値は大文字と小文字を区別します。
• OR 演算子はありません。すべての WHERE 条件は AND で結合されます。
• JOIN、GROUP BY、HAVING、サブクエリは使用できません。

WHERE 演算子

演算子	例
=, !=, >, <, >=, <=	campaign.status = 'ENABLED'
IN, NOT IN	campaign.status IN ('ENABLED', 'PAUSED')
LIKE, NOT LIKE	campaign.name LIKE '%brand%'（大文字と小文字を区別しません）
REGEXP_MATCH	campaign.name REGEXP_MATCH '(?i)brand'
BETWEEN ... AND ...	segments.date BETWEEN '2026-01-01' AND '2026-01-31'
DURING	segments.date DURING LAST_30_DAYS
IS NULL, IS NOT NULL	ad_group_ad.ad.final_urls IS NOT NULL
CONTAINS ANY/ALL/NONE	繰り返しフィールド用

日付のフィルタリング

カスタム範囲：

WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'

事前定義された範囲（DURING を使用）：

• TODAY、YESTERDAY
• LAST_7_DAYS、LAST_14_DAYS、LAST_30_DAYS（今日を含みません）
• THIS_MONTH、LAST_MONTH
• THIS_WEEK_SUN_TODAY、THIS_WEEK_MON_TODAY
• LAST_WEEK_SUN_SAT、LAST_WEEK_MON_SUN
• LAST_BUSINESS_WEEK

よく使うリソース名（FROM 句）

エンティティ： customer、campaign、campaign_budget、ad_group、ad_group_ad、ad_group_criterion、campaign_criterion

ビューリソース（指標用）： keyword_view、search_term_view、geographic_view、gender_view、age_range_view、landing_page_view、ad_group_audience_view、shopping_performance_view、click_view

その他： change_status、change_event、conversion_action、asset、bidding_strategy、label、recommendation、shared_set、shared_criterion

よく使う指標

パフォーマンス： metrics.impressions、metrics.clicks、metrics.cost_micros、metrics.ctr、metrics.average_cpc、metrics.average_cpm、metrics.interactions

コンバージョン： metrics.conversions、metrics.conversions_value、metrics.all_conversions、metrics.cost_per_conversion、metrics.conversion_rate、metrics.value_per_conversion

インプレッション シェア： metrics.search_impression_share、metrics.search_budget_lost_impression_share、metrics.search_rank_lost_impression_share、metrics.absolute_top_impression_percentage、metrics.top_impression_percentage

動画： metrics.video_views、metrics.video_view_rate、metrics.average_cpv

よく使うセグメント

日付： segments.date、segments.week、segments.month、segments.quarter、segments.year、segments.hour_of_day、segments.day_of_week

デバイス／ネットワーク： segments.device、segments.ad_network_type、segments.slot、segments.click_type

コンバージョン： segments.conversion_action、segments.conversion_action_name、segments.conversion_action_category

GAQL の重要なルール

1. 日付セグメントには日付範囲が必要です。 segments.date（または segments.week、segments.month など）が SELECT に含まれる場合、有限の日付範囲フィルターを WHERE に指定する必要があります。

2. WHERE 内の非日付セグメントは SELECT に含める必要があります。 例外として、日付セグメントは SELECT に含めなくても WHERE に指定できます。

3. 削除済みエンティティはデフォルトで含まれます。 API は削除済みエンティティを除外しません。Google Ads の UI と同じ動作にするには、campaign.status != 'REMOVED'（または同等の条件）を追加してください。

4. フィールドの互換性。 すべてのフィールドを同時に選択できるわけではありません。互換性のないフィールドに関するエラーが発生した場合は、フィールドを1つずつ削除するか、Google Ads API のフィールド互換性に関するドキュメントを参照してください。

5. ORDER BY のフィールドは SELECT に含める必要があります。 SELECT 句にあるフィールドのみで並べ替えできます。

6. 関連付けられたリソース。 FROM に含めなくても、親エンティティのフィールドを選択できます。たとえば、FROM ad_group では campaign.name を使用できます。

GAQL クエリの例

広告を表示させた検索語句：

google-ads-open-cli query 1234567890 "SELECT search_term_view.search_term, search_term_view.status, campaign.name, ad_group.name, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 50"

デバイス別のキャンペーン パフォーマンス：

google-ads-open-cli query 1234567890 "SELECT campaign.name, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status != 'REMOVED'"

インプレッション シェアの分析：

google-ads-open-cli query 1234567890 "SELECT campaign.name, metrics.search_impression_share, metrics.search_budget_lost_impression_share, metrics.search_rank_lost_impression_share, metrics.clicks, metrics.impressions, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status = 'ENABLED' ORDER BY metrics.search_budget_lost_impression_share DESC"

ランディング ページのパフォーマンス：

google-ads-open-cli query 1234567890 "SELECT landing_page_view.unexpanded_final_url, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions FROM landing_page_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 20"

ユーザー属性 -- 年齢の内訳：

google-ads-open-cli query 1234567890 "SELECT ad_group_criterion.age_range.type, campaign.name, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM age_range_view WHERE segments.date DURING LAST_30_DAYS"

地域別のパフォーマンス（ユーザーの所在地別）：

google-ads-open-cli query 1234567890 "SELECT geographic_view.country_criterion_id, geographic_view.location_type, campaign.name, metrics.clicks, metrics.impressions, metrics.cost_micros FROM geographic_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.clicks DESC LIMIT 50"

広告コピーのパフォーマンス（レスポンシブ検索広告）：

google-ads-open-cli query 1234567890 "SELECT ad_group_ad.ad.responsive_search_ad.headlines, ad_group_ad.ad.responsive_search_ad.descriptions, ad_group_ad.ad.final_urls, ad_group_ad.status, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros FROM ad_group_ad WHERE segments.date DURING LAST_30_DAYS AND ad_group_ad.status != 'REMOVED' AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD' ORDER BY metrics.clicks DESC LIMIT 20"

コンバージョン アクションの監査：

google-ads-open-cli query 1234567890 "SELECT conversion_action.name, conversion_action.type, conversion_action.status, conversion_action.category, conversion_action.counting_type, conversion_action.click_through_lookback_window_days, conversion_action.view_through_lookback_window_days FROM conversion_action WHERE conversion_action.status = 'ENABLED'"

ショッピング商品のパフォーマンス：

google-ads-open-cli query 1234567890 "SELECT segments.product_item_id, segments.product_title, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.conversions_value DESC LIMIT 50"

アカウント単位の日別推移：

google-ads-open-cli query 1234567890 "SELECT segments.date, metrics.clicks, metrics.impressions, metrics.ctr, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date DURING LAST_30_DAYS ORDER BY segments.date"

ワークフローのガイダンス

ユーザーが概要を手短に知りたい場合

1. google-ads-open-cli customers を実行して、アクセス可能なアカウントを確認します
2. 最近の日付範囲を指定して campaign-stats を使い、パフォーマンスの概要を取得します
3. マイクロ単位の費用を通貨単位に換算してデータを提示します

ユーザーが詳細な分析を求めている場合

1. campaign-stats を実行して、分析対象を特定します
2. パフォーマンスの低いキャンペーンについて、ad-group-stats または keyword-stats を使って詳細を調べます
3. 特定の分析（検索語句、ユーザー属性、インプレッション シェア、ランディングページ）には、カスタム GAQL クエリを使用します
4. conversion-actions と照合して、トラッキングの設定を確認します

組み込みコマンドにない特定の指標についてユーザーから質問された場合

GAQL を使って query コマンドを実行します。一般的なケース：

• 検索語句レポート -- search_term_view を使います
• 地域データ -- geographic_view を使います
• ユーザー属性 -- gender_view、age_range_view を使います
• ランディングページ -- landing_page_view を使います
• インプレッション シェア -- campaign から metrics.search_impression_share と関連フィールドを選択します
• ショッピング商品 -- shopping_performance_view を使います
• 変更履歴 -- 詳細なログには change_event を使います

エラー処理

• 認証エラー -- アクセストークンとデベロッパートークンを確認するようユーザーに依頼します
• 「field is not compatible」 -- 一緒に選択できないフィールドがあります。互換性のないフィールドを削除して再試行します
• 結果が空 -- 日付範囲、ステータスフィルター、リクエストしたエンティティのデータがアカウントにあるかを確認します
• 「MISALIGNED_DATE_FOR_FILTER」 -- segments.month または segments.quarter でフィルタリングする場合、日付は期間の初日にする必要があります

API ドキュメントの参照先

• google-ads-open-cli のドキュメント
• Google Ads API の概要
• GAQL リファレンス
• GAQL 文法
• リソースフィールドのリファレンス（v23）
• GAQL クエリのクックブック
• セグメンテーションのルール