Hermoso は Apple Search Ads に接続し、それをエージェントが呼び出せるツールとして公開します。Claude、ChatGPT、Cursor、Codex、Cline、CLI、または通常の HTTP から使えます。apple_ads_report は、キャンペーン、広告グループ、広告、キーワード、検索語句ごとのパフォーマンスを取得します。行はデータとして返ってくるので、CSV をダウンロードして別の場所へ運び直す必要はありません。
Apple Search Ads コネクター
Apple は、広告 API 向けの OAuth フローを公開していません。そのため、接続はボタンを押すだけの作業ではなく、鍵の受け渡しになります。Hermoso が署名鍵を生成し、その公開鍵の半分を Apple Ads に貼り付けて、3つの ID を戻します。Apple Search Ads のセットアップガイドに手順があり、多くの人が見つけられない Public Key 欄の探し方も載っています。1回接続すれば、Web アプリ、MCP サーバー、CLI、REST API のすべてで同じ接続が使えます。そのため、Claude、ChatGPT、Cursor のどこからでも同じ書き出しができます。一度 Claude または ChatGPT に接続すれば、あとは頼むだけです。
レポートはその一部にすぎません。同じ接続で、キャンペーン、広告グループ、キーワードとネガティブキーワード、予算の注文、ターゲティング、キーワード提案、変更履歴まで、アカウント全体を構築・運用できます。すべてのツールは Apple Ads のチャンネルページにあります。
レポートの内容
1回の呼び出しで、5つのレベルを扱えます。apple_ads_report は キャンペーン、広告グループ、広告、キーワード、検索語句の各レベルでレポートを作成します。どの行にも、Apple 自身のダッシュボードに表示される指標が含まれます。インプレッション、タップ、インストール、費用、タップ率、タップ単価、CPA です。合計を取得することも、時間、日、週、月単位の系列を取得することもできます。行は費用の多い順に並び、1ページ最大5,000行まで返されます。要求すれば、総計の行も付けられます。App Store のレポートには配信のないエンティティも含められるため、一時停止中のキーワードは、行が消えるのではなくゼロとして表示されます。
Apple が課しているルールは2つあります。Hermoso はそれを黙って失敗させるのではなく、ツールが説明します。キャンペーンレベル未満のレポートにはキャンペーン ID が必要です (アカウント全体をカバーできるのはキャンペーンレベルのレポートだけです)。また、検索語句のレポートは、組織自身のタイムゾーンで実行され、UTC では実行されません。Apple Maps の広告も対象です。ビジネスブランドのレポートは、プロモーション対象の種類を App Store ではなく Apple Maps に変えるだけで、同じツールから取得できます。
Apple Search Ads を Google スプレッドシートに接続する
これは、Hermoso が自分で書き込む唯一の送り先です。Apple Ads の隣で Google Drive を接続し (Google の1回の認証で Drive、Sheets、Docs が使えます)、こう頼みます。「過去30日間の Apple Search Ads のパフォーマンスをキーワード別に取得し、『Apple Ads』という名前の新しいシートに入れて。」 エージェントは apple_ads_report を呼び出し、次に create_sheet を呼び出して、シートのリンクを返します。翌週は、同じ依頼に「追加して (append)」と付けます。すると append_to_sheet が、最初からやり直さずに行を追加します。
Hermoso は Google に drive.file スコープを要求します。これが届くのは Hermoso が作成したファイルと、ご自身が選んだファイルだけで、Drive 全体には届きません。タブの置き換えや書式設定まで含む詳しい手順は、Apple Search Ads を Google スプレッドシートに接続するにあります。
Apple Search Ads を Looker Studio に書き出す
Hermoso には Looker Studio のネイティブ コネクターがありません。ないものがあるとは言わないことにしています。それも必要ありません。Looker Studio は Google スプレッドシートを、独自の標準コネクターで読み込めます。そのため、そのシートが橋渡し役になります。
- エージェントにレポートを1つのタブへ書き込ませます。 粒度は日単位で、キーワードごと・日ごとに1行、ヘッダー行と日付の列があるようにします。日付の列は日付形式にしてください (
format_sheetで設定できます)。そうすると Looker Studio がそれを日付として読み込みます。 - シートをデータソースとして追加します。 Looker Studio でデータソースを作成し、Google スプレッドシートを選んで、そのスプレッドシートとタブを指定します。「1行目をヘッダーとして使用」はオンのままにしてください。
- レポートを一度作ります。 日別の費用、インストール単価 (CPA) のキーワード別、キャンペーン別のインストール数など、毎週の月曜日にスプレッドシートで作り直しているものを何でも作ってください。
- 行を追加し続けます。 毎週、エージェントが同じタブに新しい行を追加し、ダッシュボードは次回のデータ更新で反映します。Looker Studio はヘッダーでフィールドを対応づけるため、実行のたびに列名を同じに保ってください。
同じシートは、Power BI と Tableau でも使えます。どちらも独自の Google スプレッドシート コネクターを備えています。
Apple Search Ads を JSON に書き出す
スプレッドシートではなく生の行データがほしい場合は、3つの方法があります。どれも同じ接続を使います。
REST API。 Hermoso のすべてのツールは、MCP と CLI のタブでアプリ内に作成した API キーを使い、POST /v1/tools/{name} で呼び出せます。リクエストのボディはツールの引数で、応答の data フィールドが構造化された結果になります。行は data.rows にあります。
curl -sX POST https://app.hermoso.ai/v1/tools/apple_ads_report \
-H "Authorization: Bearer hmk_..." -H 'content-type: application/json' \
-d '{"level":"keyword","campaignId":"1234567890","startTime":"2026-09-01","endTime":"2026-09-07","granularity":"DAILY"}' \
| jq '.data.rows' > apple-search-ads.jsonCLI。 npx -y hermoso call apple_ads_report --json '{...}' --structured は、同じ構造化された結果を JSON で表示します。そのままファイルへリダイレクトしたり、別のスクリプトにパイプしたりできます。
エージェント。 どのチャットでも、行を JSON で頼めば、頼んだ形に整えられた行が返信に入ります。
長いレポートでは、limit で1ページ最大5,000行まで指定し、offset で次のページへ移ります。結果の hasMore で、さらにページがあるかどうかがわかります。レポートを読んでも、クレジットは消費されません。API の完全なリファレンスは開発者向けドキュメントにあります。
そのほかの送り先
「直接」は、Hermoso が書き込むことを意味します。それ以外は、お使いのツールが自分で行う1つの手順です。
- Google スプレッドシート、Google ドキュメント、Google ドライブ、OneDrive: 直接。
- Looker Studio、Power BI、Tableau: シート経由。 それぞれ独自の Google スプレッドシート コネクターを使います。
- BigQuery: シート経由、またはご自身のエージェント経由。 BigQuery は Google スプレッドシートを外部テーブルとしてクエリできます。BigQuery クライアントとプロジェクトの認証情報があるところでエージェントを動かしていれば、Hermoso が返した行をそのままテーブルに挿入できます。
- Excel: シートまたはファイル経由。 シートを .xlsx としてダウンロードするか、エージェントに Google ドライブか OneDrive にファイルを置いてもらいます。
- PostgreSQL、Redshift、Snowflake、その他のデータウェアハウス: ご自身のエージェントか API 経由。 Hermoso は JSON を返します。データベースの認証情報を持つ側が書き込みます。Hermoso はウェアハウスの認証情報を保持しません。
毎週の書き出しを自動化する
プロンプトそのものが自動化になります。たとえば、「毎週月曜日に、先週の Apple Search Ads のパフォーマンスをキャンペーンごとのキーワード別に取得し、Apple Ads シートに追加して、どのキーワードの CPA が最も動いたかを教えて」と頼めば、それだけで完結したジョブになります。ご利用のクライアントが持つスケジュール機能 (Claude や ChatGPT のスケジュールされたタスク、または Hermoso CLI か API を呼び出す cron ジョブ) で定期実行すれば、シートと、それを読むすべてのダッシュボードが最新に保たれます。
同じ接続でアカウントを編集できるため、レポートと修正が1か所にまとまります。あるキーワードの CPA が2倍になったことにエージェントが気づけば、同じ会話の中で、そのキーワードを一時停止させたりネガティブキーワードを追加したりできます。
よくある質問
Apple Search Ads のデータはどうやって書き出しますか？
一度 Apple Ads を Hermoso に接続し、取得したいレポート (たとえば先週のキーワード別パフォーマンス) をエージェントに頼みます。apple_ads_report ツールが Apple のレポート API からデータを取得し、エージェントがそれを Google スプレッドシートに書き込むか、JSON で渡すか、その両方を行います。
Apple Search Ads を Google スプレッドシートに接続できますか？
はい。Hermoso で Apple Ads と Google Drive を接続してから、レポートをシートに入れるようエージェントに頼んでください。エージェントは create_sheet で新しいシートを作るか、append_to_sheet で既存のシートに行を追加します。これを毎週繰り返すこともできます。
Apple Search Ads を Looker Studio に書き出せますか？
はい。Google スプレッドシート経由で可能です。Hermoso には Looker Studio のネイティブ コネクターがありません。エージェントがレポートをシートに書き込み、そのシートを Looker Studio で一度 Google スプレッドシートのデータソースとして追加すれば、追加されるたびに、ダッシュボードの次回更新で反映されます。
Apple Search Ads のデータを JSON で取得するにはどうすればよいですか？
API キーを使って Hermoso API の POST /v1/tools/apple_ads_report を呼び出し、応答の data.rows を読み取ってください。または CLI で hermoso call apple_ads_report --json '{...}' --structured を実行します。どちらも同じ行を JSON で返します。
Apple Search Ads の API はありますか？
はい。Hermoso はその API の上に作られています。apple_ads_report は、キャンペーン、広告グループ、広告、キーワード、検索語句のパフォーマンスを扱い、ほかの Apple Ads ツールがアカウントの構築と管理を行います。
検索語句のレポートは取得できますか？
はい。検索語句のレベルを指定し、キャンペーン名を指定してください。Apple は検索語句をキャンペーンごとにしか返さず、その時間帯は組織自身のタイムゾーンです。
1回のレポートで何行まで返されますか？
1ページ最大5,000行で、費用の多い順に並びます。さらにページがあるかどうかは、エージェントに伝えるフラグで示されます。ほとんどのアカウントでは、毎週のキーワード別レポートは1ページに収まります。
Apple Maps の広告も対象ですか？
はい。ビジネスブランドのキャンペーンのレポートは、同じツールから取得できます。プロモーション対象の種類を App Store ではなく Apple Maps に設定してください。
セットアップには開発者が必要ですか？
いいえ。一度アプリで Apple Ads を接続したら、エージェントに普通の言葉で頼むだけです。先週分をキーワード別に取得してシートに入れて、と言えば済みます。API と CLI は、スクリプトで自動化したい場合のためにあります。