GAQLの書き方を実際に使ってわかった5つのコツ

Google広告APIを触り始めると、最初の壁が認証、次の壁がGAQL（Google Ads Query Language）の書き方だ。SQLに似ているのに微妙に違い、公式リファレンスは英語で量も多い。数千万円規模の広告をAPIで自動集計する中で、つまずいた点と、そのままコピペで動く形が見えてきた。この記事は、GAQLを「読める」から「自分で書ける」に変えるための実践ガイドだ。3要素、コピペ用クエリ5本、落とし穴3つ、日付指定までまとめる。認証段階でつまずくなら、先にGoogle広告APIをPythonで動かす手順と初回の壁を読むと早い。

GAQLはSQLに似た「3要素」でできている

GAQLはSQLに似ているが、GROUP BYもJOINも書かない。1つのresource（主リソース）を選び、そこにmetrics（数値指標）とsegments（分割軸）を足すだけの構造だ。公式ドキュメント（developers.google.com/google-ads/api/docs/query/structure）でも、この3要素の組み合わせがクエリの中心だと説明されている。

ざっくり役割はこうだ。（1）resource＝何を主軸に見るか。campaign、ad_group、keyword_view、search_term_viewなど。（2）metrics＝clicksやcost_micros、conversionsといった集計済みの数値。（3）segments＝segments.dateやsegments.deviceなど、行を分割する軸。この3つをSELECTに並べ、FROMでresourceを1つ指定し、WHEREで絞り込む。基本形は「SELECT 項目 FROM リソース WHERE 条件」だけだ。

SQLとの一番の違いは、集計とグルーピングが暗黙で走る点だ。segmentsをSELECTに足すと、そのままGROUP BYを書いたように行が自動で分割される。この挙動を知らないと、後述する「行が勝手に増える」罠に必ずぶつかる。

そのままコピペで使えるGAQLクエリ5本

まずは動くものを手元に置くのが最短だ。以下の5本は、実運用でそのまま叩いている頻出クエリだ。ブックマークして、campaign.statusや日付範囲を自分の環境に書き換えて使ってほしい。すべてsearch_streamに渡せばそのまま結果が返る。

（1）キャンペーン別コスト・CV：SELECT campaign.name, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC

（2）キーワード別実績（配信中のみ）：SELECT ad_group_criterion.keyword.text, metrics.clicks, metrics.cost_micros, metrics.conversions FROM keyword_view WHERE segments.date DURING LAST_30_DAYS AND campaign.status = 'ENABLED' ORDER BY metrics.cost_micros DESC LIMIT 500

（3）検索語句レポート：SELECT search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.conversions FROM search_term_view WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.impressions DESC

（4）曜日別の消化：SELECT segments.day_of_week, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS

（5）デバイス別の実績：SELECT campaign.name, segments.device, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS

ポイントは、resourceごとに使えるmetricsとsegmentsが決まっていることだ。keyword_viewでしか取れない属性、search_term_viewでしか取れない属性がある。迷ったら公式のQuery Builderで候補を確認すると速い。曜日・時間帯の集計を深掘りしたい場合はGoogle広告の曜日・時間帯別CPAをPythonで集計にクエリと後処理の実例をまとめてある。

実運用でハマった落とし穴3つ

クエリが通っても、返ってきた値の扱いで事故る。実際にやらかした3つを共有する。

落とし穴1：cost_microsは円ではない。metrics.cost_microsは「100万分の1通貨単位（micros）」で返る。生値が「1500000000」だったとき、そのまま15億円と読むと桁を3つ間違える。正しくは1,500,000,000÷1,000,000＝¥1,500だ。円に直すコツは単純で、cost_microsは必ず÷1,000,000（1e6）してから表示する。CPAを出すなら「cost_micros ÷ 1e6 ÷ conversions」だ。この換算を挟まずレポート化して、桁違いの数字をそのまま出しかけたことがある。

落とし穴2：segmentsを足すと行が増える。segments.deviceをSELECTに入れると、キャンペーン1件が「モバイル・PC・タブレット」の複数行に割れる。行数が2〜3倍になり、単純にcost_microsを合計すると当然正しい総額になるが、キャンペーン単位で見たいのに行が割れて混乱する。さらに注意すべきは、segments.conversion_actionを足したときだ。conversionsはCVアクション別に割れるが、clicksとimpressionsは各行に同値が繰り返される。行方向に安易にSUMすると多重計上される。segmentsは必要な分割軸だけを足すのが鉄則だ。

落とし穴3：大量行はページングかストリームで取る。行数が多いクエリを通常のsearchで叩くと、next_page_tokenで分割取得する必要がある。トークン処理を書き忘れて先頭ページしか取れていないのに「全件取った」と誤認しやすい。search_streamを使えばページング不要で全行がストリームで返るので、レポート用途ならこちらが安全だ。連続で叩きすぎるとRESOURCE_EXHAUSTED（レート上限）が返るので、リトライとスリープも入れておく。

日付範囲はDURINGとBETWEENを使い分ける

GAQLの日付指定は2通りある。公式のDate Rangesガイド（developers.google.com/google-ads/api/docs/query/date-ranges）に沿うと、定型の期間はDURING、任意の期間はBETWEENだ。

定型期間：WHERE segments.date DURING LAST_30_DAYS。ほかにLAST_7_DAYS、THIS_MONTH、LAST_MONTH、LAST_QUARTERなどが使える。日次バッチで「直近30日」を回すならこれが一番楽だ。

任意期間：WHERE segments.date BETWEEN '2026-08-01' AND '2026-08-31'。ここでハマりやすいのが、日付はシングルクォートで囲む必要がある点だ。クォートを外すとクエリが弾かれる。月次の締めや、特定キャンペーン期間だけを切り出すときはBETWEENを使う。

日付を1本のクエリで複数条件と組むときは、ANDでつなぐだけでいい。例：WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS。文字列（statusやdevice）はシングルクォート、数値（impressionsやcost_micros）はクォートなし、が基本ルールだ。

ここまでのクエリをつなげば、日次で「配信中キャンペーンのコストとCPA」を無人で吐き出せる。取得データを報告資料に落とす工程は、AIツールで一気に短くできる。

［PR］ 取得したデータをそのまま報告資料・スライドに整えるなら、以下のAIツールが使える。AIスライド作成ツール「イルシル」を試してみる

まとめ

GAQLは「resource・metrics・segmentsの3要素」と割り切れば怖くない。まずはコピペ5本を動かし、cost_microsは÷1e6、segmentsは必要な軸だけ、日付はDURINGとBETWEENの使い分け、この3点を押さえれば実運用に耐える。次のアクションは、手元のアカウントIDでクエリ（1）を1本流してみることだ。値が返れば、あとは書き換えるだけで自分のレポートが作れる。

実務でそのまま使いたい人へ

本記事のクエリの完全版（Pythonからの実行コード・search_streamの雛形・レポート整形つき）は、運営者のnote（note.com/ryo_ai_hack）で公開している。実データに基づく広告API自動化の実践ガイドをまとめて読める。

DMM 生成AI CAMP

コメント

コメントを投稿

このブログの人気の投稿

Claude Skills販売で月5万稼ぐ3ステップ実践

イメージ
2026年、Anthropicが公開した「Claude Skills」が新たな副業の入口として注目を集めている。SKILL.mdというMarkdown形式の手順書を1枚書くだけで、誰でも自分の業務ノウハウをAIワークフローとして販売できる仕組みだ。海外では非エンジニアが50日で5,000ドルを売り上げた事例も登場し、日本でも参入の動きが加速している。今回は「Claude Skills 販売 副業」を軸に、月5万円を狙うための3ステップを具体的に解説する。コードは一切不要、初期費用もほぼゼロで始められる。 Claude Skillsとは何か:販売できる理由 Claude Skillsは、Claude Codeが特定タスクを実行する際に読み込む「再利用可能な指示書」である。実体はSKILL.mdというテキストファイル1枚で、業務手順を自然言語で記述するだけで動く。プログラミング言語は必要なく、日本語で「請求書を読み取り仕訳を生成する」「議事録から議題別サマリを作る」といった手順を構造化して書けば成立する。 販売できる理由は3つある。第一に、Anthropicの審査やマーケットプレイス登録が不要で、自分のサイトやGumroad経由で即販売できる。第二に、業務知識そのものが資産になるため、士業・人事・経理など専門職の暗黙知が高値で売れる。第三に、購入者はファイルをClaude Codeに置くだけで使えるため、サポート負荷が極めて低い。海外メディアagent37の報告では、税務処理を自動化するSkillが1本79ドルで継続的に売れている。 月5万円のリアルな単価設計 1本2,980円のSkillを月17本売れば達成できる。1本9,800円なら月5本で到達する。高単価帯は専門業務向け、低単価帯は汎用ツール系という棲み分けが定石となっている。 ステップ1:売れるSkillテーマを30分で決める 最初の関門はテーマ選定である。売れるSkillには共通点が3つある。「毎週繰り返す業務」「結果物がテキストかコード」「担当者の判断が定型化できる」の3点だ。この条件を満たす自分の業務を15個書き出し、上位3つに絞り込む作業を30分で行う。 具体例を挙げる。広告運用者なら「日次レポートのSlack要約Skill」、人事なら「面接フィードバック整形Skill」、ライターなら「SEO見出し構成生...
続きを読む

Claude CodeでExcel自動化副業を月5万にする手順

イメージ
Claude Codeを副業に使いたいが、何から手をつければ収入につながるのか見えにくい。本記事は、需要が安定しているExcel自動化案件に的を絞り、3週間で初案件を獲得し月5万円までスケールさせる具体的な手順をまとめる。コーディング未経験でも、手順どおりに進めれば動くものを納品できる構成にした。 なぜExcel自動化が初心者の最短ルートなのか クラウドソーシングで需要が枯れない領域がExcel関連だ。ランサーズやクラウドワークスでは「VBAでの集計自動化」「データ整形」「請求書生成」が常時数百件単位で募集されている。単価は1案件3,000〜30,000円で、納期も短い案件が多い。 従来は VBAの知識 が壁だった。だがClaude Codeは自然言語の指示からVBAコードを生成し、ターミナル上で実行・修正まで完結する。リベシティの解説によれば、Excel自動化はClaude Code副業16ジャンルの中で初心者が最も入りやすい分野とされている。 参考: リベシティのClaude Code活用例まとめ 準備するもの（初期費用は月3,000円のみ） Claude Pro契約: 月額20ドル（約3,000円） Node.js: 公式サイトから無料でインストール Microsoft Excel: すでに持っているはず クラウドソーシングのアカウント: ランサーズかクラウドワークス 初期投資はClaude Proの月3,000円のみ。1案件取れれば即回収できる水準だ。インストール手順は Uravationの2026年最新ガイド に図解で載っている。 3週間ロードマップ：初案件獲得まで 1週目：Claude Codeで動くものを3つ作る 最初の壁は「指示の出し方」だ。いきなり案件に応募せず、まず手元のExcelで3つの小さな自動化を作る。例として「フォルダ内のCSVを1つに統合」「請求書テンプレへの差し込み」「重複行の検出」が定番だ。各15〜30分で完成する。 この段階で重要なのは、生成されたVBAを 必ず自分で1行ずつ読む こと。読めなくても動作の意図は把握する。後工程のエラー対応で効いてくる。 2週目：ポートフォリオを2本作る 応募時に提示する成果物を準備する。「営業日報の月次集計を5秒で完了するマクロ」「100枚の請求書PDFを一括生成するツール」のように、効果を秒数や...
続きを読む

Yahoo広告APIをPythonで自動化して詰まった5つの罠

イメージ
Yahoo!広告のデータをPythonで自動取得しようとして、公式リファレンスの前で手が止まった経験はないだろうか。検索で出てくるのはPHPやGoogle Apps Scriptの記事ばかりで、Pythonの実装例は驚くほど少ない。実際に動かすと、Google広告APIとは作法がまるで違う。とくにレポート取得は「すぐ取れない」独特な仕様で、初見だと必ずつまずく。ここでは、月数千万円規模の運用でレポート自動化を組んだとき実際に踏み抜いた5つの罠と、その回避策を実装目線でまとめる。読み終えれば、非同期レポートの待ち受け処理まで自力で書けるようになる。 Yahoo広告APIをPythonで叩く全体像 まず処理の流れをつかむ。Yahoo!広告APIでレポートを取るまでは、大きく3ステップだ。1つ目がOAuth 2.0でのアクセストークン取得、2つ目がレポート定義の登録、3つ目が生成完了を待ってのダウンロードである。Google広告APIのように「クエリを投げたら即データが返る」設計ではない点が最大の違いだ。 通信はすべてHTTPSのPOSTで、リクエストもレスポンスもJSONで扱える。だからPythonなら requestsライブラリ1つ で完結する。公式SDKに頼る必要はない。認証まわりの仕様は LINEヤフー広告 API v19のリファレンス が一次情報になる。現行はv19で、URLのバージョン部分を間違えると404で弾かれる。 罠1・罠2：レポートは即取得できない「非同期ジョブ」 最初の関門がこれだ。Yahoo!広告は、事前に ReportDefinitionService へレポート定義を登録しないとデータが一切出力できない。アカウントID・レポート種別・期間・欲しいフィールドを指定して登録すると、レポートIDが返る。ここでCSVが返ると思い込むのが罠1である。 返ってくるのはIDだけで、サーバー側は裏でCSVを生成し始める。生成には数十秒から、行数が多いと数分かかる。登録直後にダウンロードを叩くと「生成中」ステータスが返り、空振りする。これが罠2だ。 対策はポーリングだ。 getReportJobで状態を数秒おきに確認 し、COMPLETEDになってから初めてダウンロードURLへアクセスする。Pythonなら「10秒sleep→状態確認→未完なら再試行、最大12回...
続きを読む