Yahoo広告APIのレポートをPythonで取る4手順

Yahoo広告のレポートをPythonで取ろうとして、最初の1本が動くまでに半日が溶けた。原因はコードの書き方ではない。Google広告やMeta広告と違い、Yahoo検索広告APIのレポートは「その場で数値が返るAPI」ではないからだ。定義を登録し、ジョブの完了を待ち、CSVをダウンロードし、後片付けをする。この4手順を知らずにレスポンスをJSONとして読もうとすると、出てくる例外の文面からは原因がまったく読み取れない。ここでは当月消化を毎日取得している実運用コードをもとに、4手順の流れとつまずいた箇所を書く。対象はYahoo検索広告API v19だ。

レポート取得は「4手順のジョブ処理」になる

Yahoo検索広告APIのレポートは、1回のリクエストで数値が返らない。実際の流れは次の4手順だ。

  • (1) ReportDefinitionService/add でレポート定義を登録し、reportJobId を受け取る
  • (2) ReportDefinitionService/get を叩き、reportJobStatus が COMPLETED になるまで待つ
  • (3) ReportDefinitionService/download でCSVを受け取る
  • (4) 不要になった定義を remove で片づける

実測では、(2)の完了まで3秒から15秒かかった。運用コードでは3秒間隔で最大40回ポーリングしている。日次バッチなら十分な余裕だ。エンドポイントは ads-search.yahooapis.jp/api/v19 になる。ドメインを ads.yahoo.co.jp と書くと404が返る。旧バージョンのv16やv17を叩くと code:0004 URL not found だ。

もう1つ、最初に必ず詰まるのがヘッダーである。リクエストには MCC のIDを x-z-base-account-id ヘッダーに入れる必要がある。これを付け忘れると code:0001 Invalid Request が返る。さらに厄介なのは、レポート以外の読み取り系APIだとエラーにならず0件で返ってくることだ。「キャンペーンが1本もない」と読み違えた。仕様の詳細はLINEヤフー広告の公式リファレンスにある。Yahoo広告API全般のつまずきどころはYahoo広告APIをPythonで自動化して詰まった5つの罠にまとめてある。

罠1: bodyとfieldsは「通る最小構成」から始める

add に渡すbodyに余計なフィールドを入れると、code:0005 requestKey=format requestValue=null のようなエラーが返る。この文面を素直に読むと「formatの値がnullだから埋めろ」と解釈してしまう。実際の意味は逆だ。そのフィールドをAPIが知らない、つまり消せという意味である。

しかもこのエラーは先頭の1つしか返さない。余計なフィールドが5個あれば、5回往復して1個ずつ削ることになる。最小構成で通してから足すほうが速い。

v19で通った最小のbodyは accountId / reportName / reportType / reportDateRangeType / dateRange / fields の6つだけだ。逆に、他媒体の感覚で入れたくなる format・encode・isTemplate・intervalType・dateRangeType・reportLanguage・reportSkipReportSummary・reportCompressType・reportIncludeDeleted は、すべて書かない。reportName は同名だと衝突するので、末尾にUNIX時刻を付けてユニークにしている。

v19に無いフィールドはTypeErrorになって返る

fields の指定にも落とし穴がある。KEYWORDS レポートで AD_GROUP_NAME・MATCH_TYPE・AVG_CPC を指定すると V0001 が返る。これらはv19に存在しないためだ。

問題はエラーの出方にある。addのレスポンス自体は200で返り、中の reportDefinition が null になる。そのため reportJobId を取り出す行で TypeError が出る。エラーの発生行と本当の原因が離れているので、デバッガでレスポンスの中身をそのまま表示するまで気づけなかった。

実際に使えたのは CAMPAIGN_NAME / KEYWORD / COST / CLICKS / IMPS / CONVERSIONS だ。平均CPCのフィールドは無いので、COST を CLICKS で割って自分で出す。この割り算をレポート側でなくPython側に置いたほうが、クリック0除算の扱いを自分で決められて都合がよかった。

回避策は単純で、add のレスポンスを変数に入れたら、reportJobId を取りに行く前に errors の有無を必ず判定する。1行増やすだけで、原因不明のTypeErrorが「どのフィールドが悪いか」まで書かれたエラーメッセージに変わる。

罠2: downloadはJSONではなくCSVを返す

最後の罠がいちばん時間を取られた。ReportDefinitionService/download のレスポンスはCSVのプレーンテキストである。他のサービスと同じ共通関数で叩くと、内部で resp.json() が走って Expecting value: line 1 column 1 (char 0) になる。認証まわりを疑って1時間浪費した。

対処は、download だけ共通のpost関数を経由させず、requests.post に認証ヘッダーを自分で組んで渡し、resp.text を読むことだ。なお ReportService/download というパスは存在しない。404が返る。正しいのは ReportDefinitionService 側である。

CSVを読むときにもう1つ注意がいる。ヘッダー行が日本語で返ってくる。1列目が「キャンペーン名」、2列目が「コスト」だ。英語のフィールド名でカラムを引き当てる実装にすると、指定は英語なのに戻りは日本語なので全部外れる。列名でなく順序で読むか、日本語のヘッダーで照合するかを最初に決めておく。

消化額がちょうど2倍になった原因と検算の手順

実装が通ったあと、集計した当月消化が管理画面の値のちょうど2倍になった。原因はCSVの最終行が合計行だったことだ。この行はキャンペーン名の列が空欄で返る。全行をループして足すと、明細と合計を二重に足すので必ず2倍になる。

「ちょうど2倍」は幸運な壊れ方だった。危ないのは、日次バッチに載せてから誰も突き合わせなくなることだ。本番に載せる前に、API合計と管理画面の当月消化を1回だけ手で照合する工程を入れている。3媒体をまとめて扱う場合の統合の考え方は広告3媒体レポート統合をPythonで実装した手順に書いた。

この手順の完全版はnoteの実践ガイドにまとめている。

コピペで使えるYahooレポート実装チェックリスト

ここまでの内容を、着手前に上から確認できる形にした。ブックマークして、自分の環境に合わせて書き換えて使ってほしい。

  • (1) エンドポイントは ads-search.yahooapis.jp/api/v19 か。旧バージョンを叩いていないか
  • (2) 全リクエストに x-z-base-account-id（MCCのID）を付けているか
  • (3) add の body は accountId / reportName / reportType / reportDateRangeType / dateRange / fields の6つだけか
  • (4) reportName に時刻を足してユニークにしているか
  • (5) fields は CAMPAIGN_NAME / KEYWORD / COST / CLICKS / IMPS / CONVERSIONS の範囲に収まっているか
  • (6) add の直後に errors を判定してから reportJobId を取り出しているか
  • (7) get のポーリングは3秒間隔・上限回数つきで、タイムアウト時に例外を投げているか
  • (8) download だけは resp.text で受けているか。json() を通していないか
  • (9) CSVは1行目のヘッダーと、キャンペーン名が空の最終行を捨てているか
  • (10) 本番に載せる前に、API合計と管理画面の当月消化を1回突き合わせたか

(3)(6)(8)(9)の4つが、今回半日を溶かした箇所そのものだ。ここだけ先に潰せば、初回の実装は1時間ほどで通る。

［PR］ 取得した数値をそのままクライアント向けの報告資料にするなら、スライド生成を自動化するツールも併用できる: AIスライド作成ツール「イルシル」を試してみる

まとめ

Yahoo検索広告APIのレポートでつまずく原因は、ほぼ3つに集約される。エラー文面の意味が直感と逆であること、v19に無いフィールドが別の例外になって返ること、downloadだけCSVであることだ。この3つを先に知っていれば、実装そのものは難しくない。まずはCAMPAIGN_NAMEとCOSTの2フィールドだけで1本通し、管理画面の数値と突き合わせるところから始めるのが確実だ。そこが合えば、あとはfieldsを足していくだけで済む。

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

本記事の手法の完全版（実際のコード・テンプレート・つまずき対処つき）は、運営者のnote（note.com/ryo_ai_hack）で公開している。実データに基づく実践ガイドをまとめて読める。

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回...
続きを読む