広告API使いやすさランキング

こんにちは。

テックリードのTerukiです。
前回の記事でETLツール自作の話をしましたが、今回はその過程で得た広告APIの使いやすさなどをランキング形式で発表しようかと思います。

https://qiita.com/omt_teruki/items/684dc3ee454510f52491

完全にネタ記事ですのでエンタメの一つとして見てもらえたら嬉しいです:pray:
主観が多分に含まれますのでその辺りもあしからず。

# 対象の広告API
- Facebook広告
- Google広告
- X広告
- TikTok広告
- Yahoo広告
- Microsoft広告

# ランキング
この記事では下記のランキングを(勝手に)決めたいと思います。

- 申請の承認の早さランキング
- 申請の簡単さランキング
- ドキュメントの読みやすさ・分かりやすさランキング
- 実装の難易度の高さランキング

※この記事の内容は2024年10月から12月の間にかけて実際にあった内容をベースとしているので、今後も似たような結果になるとは限りません:pray:


# 申請の承認の早さランキング
APIを使えるようにするためのリードタイムみたいなランキングです。
申請に必要なものを揃えるための時間は含んでいません。

微妙に需要がある気がします。


## 1位 Microsoft広告
そもそも承認という概念がありませんでした。

自分のアカウントで広告管理画面にアクセスできるようにしてもらった後、開発者アカウントを作成してAzure Portalからアプリの登録をするとすぐに使えます。

Azure Portalの操作に慣れていれば結構すぐできると思います。

https://learn.microsoft.com/ja-jp/advertising/guides/?view=bingads-13

## 2位 Yahoo広告

所要時間：5分

時間的に自動承認のようです。
申請者にルートMCCアカウントへの管理者権限がないとリジェクトされるので注意です。

https://ads-developers.yahoo.co.jp/ja/ads-api/startup-guide/apply-api-use.html

## 3位 X広告

所要時間：1時間

申請用Googleフォームに必要事項を入力すると承認完了メールが届きます。

事前に弊社の営業担当に頭出しをしていたおかげか、5 business daysと書かれていたものの相当早く承認されました。
担当がついているなら先に話しておくと良さそうです。

https://developer.x.com/en/portal/dashboard

## 4位 Facebook広告

所要時間：1日

こちらは自社の広告アカウントを参照するだけだったら承認は不要です。

ただし、API利用量が多い場合は「広告管理スタンダードアクセス」を申請して上限を上げてもらう必要があります。
Oh my teethの利用方法では申請不要のDevelopment Accessではレートリミットに引っかかってしまうので申請しました。

https://developers.facebook.com/docs/features-reference/ads-management-standard-access/

注意点として、「広告管理スタンダードアクセス」は単体では申請できず他に「ads_read」や「ads_management」の権限と一緒に申請する必要があります。(単体で申請すると一瞬でリジェクトされます(一敗))

申請画面には5日程度と書いてありましたが、割とすぐに返事が来るので好印象でした。

## 5位 TikTok広告

所要時間：2週間

開発者ポータルからアプリを作成後、利用方法などを英語で送信します。

https://business-api.tiktok.com/portal

1週間経っても全く音沙汰がなく、しびれを切らした時に運良くTikTokの営業担当に繋がることができたので確認してもらえました。
承認担当にプッシュしてもらえたので営業担当にお願いは有効な手だと思います。

ちなみに承認されても特に承認された的なメール通知はありませんでした。（営業担当からは連絡がありました）

## 6位 Google広告

所要時間：6週間

めちゃくちゃ時間がかかりました。

Google広告APIのグループでは、このグループのスコープ外の申請についての投稿が大量に出てくるくらいには遅いです。

https://groups.google.com/g/adwords-api

定型返信として、該当の問い合わせフォームを案内されますがそこで問い合わせても結局返事は来ません。

私も忘れた頃に急に承認メールが飛んできたのでびっくりしました。

BigQueryのGoogle広告の連携機能が優秀のため、こちらで事足りる人はこれで良いと思います。

https://cloud.google.com/bigquery/docs/google-ads-transfer?hl=ja

# 申請の簡単さランキング

申請を送信するまでの工程がどのくらい簡単かをランキングにしたものです。

## 1位 Yahoo広告

日本勢というのもあり、非常に分かりやすかったです。

https://ads-developers.yahoo.co.jp/ja/ads-api/startup-guide/apply-api-use.html

Oh my teethは広告主なので運営サイトURLや法人番号を入力する程度で何か文章を考える必要はありませんでした。
ツールプロバイダーなどでは別のなにかを要求されるかもしれません。

## 2位 TikTok広告

英語での入力にはなりますが、アプリの名前、説明、リダイレクトURL、必要な権限を入力するだけです。

項目も少ないので比較的簡単だと思います。

今回はReporting権限以外申請していないので、自社で分析するためと英語で書くだけで十分そうです。


## 3位 X広告

専用Googleフォームに会社や担当者の情報、会社のXアカウント、事前に作成したX Developer AppのID、使う目的を英語で記載して最後に規約に同意するチェックをすると完了です。

英語での記載は必要になりますが、短文で済むのでそこまで苦ではありませんでした。

Googleフォームなのがちょっと面白いですね。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3192685/6d6fd760-aca0-02a6-aed4-e0168ff2ffb1.png)

承認も比較的早かったですし、文句はあまりありません。

## 4位 Microsoft広告

XやTikTokと違い、用途や説明を英語で書いたりする必要はありませんがAzure Portalからアプリの登録を行い、それと広告API側の連携をするのは慣れていないと苦戦します。

私は以前やっていた別のお仕事でAzure Portalには慣れっこだったのであまり苦戦しませんでしたが、Entra IDのアプリの登録にたどり着くのも人によっては一苦労だと思います。

私が自社のEntra IDの管理者権限を持っているため権限周りでたどり着けないなどはありませんでしたが、もし自社の情シスなどが管理している場合はアプリの作成をお願いする必要が出てくるかもしれません。

もしくは自分で新しいテナントを作ることになりそうです。

## 5位 Google広告

控えめに言ってもかなり面倒です。

https://developers.google.com/google-ads/api/docs/access-levels

MCCアカウントのIDや会社のWebサイト、会社のビジネスモデルの説明を英語で記載します。

それはまだ良いのですが、下記のサンプルドキュメントのようなものを作成してAPIの用途や画面イメージを共有します。

https://docs.google.com/document/d/1oxtkAuxoZF15GYdDvR021QXKrDX0VL9M5t8r7sW7-3o/edit?tab=t.0

Oh my teethではフロントエンドのないETLツールだったので「コンソールアプリなので画面なんてないよ」とやんわり記載してお茶を濁しました。

一応OKだったようです。


## 6位 Facebook広告

※レートリミットを超えない範囲では申請は不要のためランキングとしては対象外になります

「広告管理スタンダードアクセス」と「ads_read」を申請した時の情報です。

ads_readの申請には、たとえ自社以外で使わないアプリでも外部に公開する体の申請をしないといけません。

申請には、ユースケースや必要とする詳細な理由、さらには開発するアプリの画面キャプチャを説明動画としてアップロードする必要があり、非常に大変でした。

申請フォームは綺麗な日本語ですが、実際にレビューしてくれる担当者は恐らく英語しか分からないため英語で申請しないとうまく伝わりません。(伝わりませんでした(1敗))

例のごとくフロントエンドのないETLツールだったので画面キャプチャなど見せられるものはありませんでしたが、とりあえずBigQueryに連携されたあとLooker Studioで可視化されるんですよ的なものを雑に録画して提出しました。

何回か往復しましたが最終的には承認してもらえました。


# ドキュメントの読みやすさ・分かりやすさランキング

このランキングは読み手のスキルセットにだいぶ依存するので人によってランキングは変わってくると思います。あしからず:pray:

## 1位 Google広告

Google広告のAPIはGAQLという専用言語で広告データを取得してきます。

https://developers.google.com/google-ads/api/docs/reporting/overview

若干クセはありますが設計思想の理解は容易なので、勝手を覚えてしまえばドキュメントを読まなくても欲しいデータを取得してくることができると思います。

かなりリッチなクエリビルダーも容易されていて、GUIでポチポチするとGAQLを組み立ててくれます。

https://developers.google.com/google-ads/api/fields/v18/ad_group_ad_query_builder

これのおかげで自分のやりたいことを実現するには何をしたら良いのかわりとすぐに分かるようになるかなと思います。


## 2位 Yahoo広告

OpenAPI Specが用意されているのでそれを読めば一発です。

https://ads-developers.yahoo.co.jp/reference/ads-search-api/v15/

ただし、上記のAPIリファレンスはいまいちページの構造がすっと入ってこず個人的には見づらかったです。

それでも、OpenAPI Specをよしなにすれば良いので他の媒体と比較して分かりやすい部類に入ると思います。

## 3位 Facebook広告

Graph APIを使ってデータを取得します。

Microsoft Graphを使ったことがある人なら理解は容易そうです。

https://developers.facebook.com/docs/graph-api

https://developers.facebook.com/docs/marketing-apis/

Metaのドキュメントページは分量的にはたくさんあるものの、いまいち知りたい情報にうまくたどり着けません。
マーケティング担当の人も似たようなことを言っていたのでうまく言語化できませんが何かあるんだと思います。

一方、Google広告のクエリビルダーのように、補助ツールは非常に充実しておりアクセストークンデバッガーやグラフAPIエクスプローラなどのコードを書かずにAPIを実行する手段が豊富に用意されているため、そこはポイント高いです。

https://developers.facebook.com/tools/debug/accesstoken/

https://developers.facebook.com/tools/explorer/

## 4位 Tiktok広告

英語のみのドキュメントです。
とっつきづらさはありますが、腰を据えて読み込んでいけば理解は十分可能でした。

https://business-api.tiktok.com/portal/docs?id=1797738007505921

知りたい情報も多分ここにあるだろうと思うところにありますし、ちゃんと読めばちゃんと書いてあるという印象です。

コードを書き始める前にPostmanなどでいろいろ試してみるのが良いと思います。

## 5位 X広告

Postman Collectionが用意されていたり、日本語も用意されていたりパット見はよくできているドキュメントです。

https://developer.x.com/ja/docs/x-ads-api

最初は好印象でしたが、よく見るとトラップだらけでした。

日本語の記事は英語の記事と比べて内容が遅れていておかしな点がそこそこあります。

広告のメトリックを取得するためには、広告アナリティクスのページを見れば良いことは分かりますが、ここにあるAPIをどう使って取得したら良いのか、そもそもどういうふうにこれらのAPIを使ってほしいのかまるで伝わってきません。

特に分からないのは、一番細かい粒度でメトリックを見つつもキャンペーンや広告グループも結合したデータを取得したい時に何のキーで結合をすれば良いのかドキュメントを見るだけでは分からず実際にAPIを実行して多分これだろうとやらざるを得ませんでした。

レスポンスはJSONで降ってきますが、すごくパースが大変そうな形をしていて後処理に苦労します。

```json
{
  "segment": null,
  "metrics": {
  "impressions": [
    0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  ],
  "engagements": [
    0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  ]
}
```

シンプルにこのように返してきて欲しいものです。

```jsonc
[
  {
    "date": "2025-01-01",
    "impression": 0,
    "engagements": 0
  },
  {
    "date": "2025-01-02",
    "impression": 1,
    "engagements": 1
  },
  // 略
]
```
キーが何回も出現するとJSON形式においては通信量が増えるというのは分かるのですが、だったらもはやCSVで返して欲しいとも思ったり。

## 6位 Microsoft広告

ドキュメントはこちらです。

https://learn.microsoft.com/ja-jp/advertising/guides/?view=bingads-13

今どきSOAP APIなのも驚きですが、中途半端な機械翻訳もあいまって読んでも頭に入ってきません。
こんなことを言ってはアレですが、ドキュメントは読まずにC# SDKのコードと公開されているサンプルコードを読んだほうが分かりやすいと感じました。

# 実装の難易度の高さランキング

私がC#でETLを実装した時に感じた難易度をランキング形式でお届けします。

## 1位 Google広告

.NETのGoogle Ads APIのNuGetパッケージをインストールしてGAQLを実行するだけです。

GAQLはクエリビルダーで作ったものをコピペで実行できます。

下記のようなクエリを書いて見ました。

```sql
SELECT
    segments.date,
    customer.id,
    customer.descriptive_name,
    campaign.id,
    campaign.name,
    ad_group.id,
    ad_group.name,
    ad_group_ad.ad.id,
    ad_group_ad.ad.name,
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros,
    metrics.ctr,
    metrics.average_cpm,
    metrics.average_cpc,
    ad_group_ad.ad.final_urls
  FROM ad_group_ad
    WHERE
      segments.date BETWEEN '{日付}' AND '{日付}'
```

これで一番細かい粒度でのメトリックをそれぞれ抽出することができます。

非常に簡単でした。

## 2位 Yahoo広告

OpenAPI Specを使ってコードを自動生成すればSDKが完成！ということができるわけですが、Reporting機能しか使わないのにすべてのコードを生成するのはなんだかもったいないというか無駄に感じてしまったため普通にHTTPリクエストを投げるコードを書きました。

非同期ジョブを作成して終わるまでポーリングするというシンプルなもののため、そこまで苦戦する要素はないです。

ジョブが終わってCSVをダウンロードし終わった後は明示的にレポート削除をしたほうが良さそうです。

## 3位 TikTok広告

同期APIを使ってメトリックを取得することができます。

https://business-api.tiktok.com/portal/docs?id=1740302848100353

非同期APIではないので、ポーリングなどの面倒な処理は不要です。

一回のリクエストで取ってこれる日数はあんまり多くないですが、そこはループで回せば良いので比較的簡単に実装できます。

JSONで返ってくるのでBigQueryなどに入れる場合は形をCSVやJsonlに整形する必要ありです。

ちなみに非同期APIは現時点では追加で申請が必要です。(1敗)

## 4位 Microsoft広告

ドキュメントは分かりづらかったですが、SDKはマシです。

下記のサンプルを見るとイメージが湧くと思います。

https://github.com/BingAds/BingAds-dotNet-SDK/blob/9ee14a78e1edd1220a1f8b52a363d36b71a7cfd8/examples/BingAdsExamples/BingAdsExamplesLibrary/v13/ReportRequests.cs#L472

きっと設計されたのがかなり昔なんだろうなと思いつつ、一新してモダンなAPIも出してほしいですね。

## 5位 Facebook広告

Graph APIで重い処理を投げるとすぐにタイムアウトするので非同期APIの利用はマストです。

単にキャンペーンなどのメトリックが見たいだけならそこまで難しくありませんが、私たちは遷移先のURL単位で分析をしたかったので遷移先URLをレポートに含めるのは必須です。

Facebook広告のデータは下記の階層構造になっていて、遷移先URLは飛び地にあります。

- 広告アカウント
  - キャンペーン
    - 広告セット
      - 広告　ー　広告クリエイティブ(遷移先URL)

メトリックを取得できるインサイトAPIは広告までしか取得できず、広告クリエイティブの情報を取得できないためインサイトAPIだけでは遷移先URLを取得できません。

https://developers.facebook.com/docs/marketing-api/insights?locale=ja_JP

広告クリエイティブを取得するAPIはもちろんありますが、少ない件数ずつしか取得できない上、一回の取得数を増やすとすぐにエラーを吐くため一回の取得数を多くすることができません。

Oh my teethでは広告クリエイティブは万単位で存在するのですが、更新されたもののみ取得する術はなく全件洗い替えをする必要があります。

全件洗い替えは非常に時間がかかり、実行環境のLambdaの制限の15分以内で終わらないため直近取得できたメトリックに関連する広告クリエイティブのみAPIから取得し、インサイトAPIから取得したCSVに無理やり結合して実現しています。

THE ゴリ押しという感じですが商用ETLツールでは絶対できない挙動だと思うので自作の良さが出ています。

他の媒体では遷移先URLは当たり前のように取得できるのでMetaには改善してもらいたいです。

## 6位 X広告

最初にドキュメントを読んだ時は思いもよらなかった複雑さになりました。

一番細かい粒度でメトリックを取得するには、広告単位でメトリックを取得後にそれを下記の要領で結合していく必要があります。

広告メトリック　ー　広告　ー　広告グループ　ー　キャンペーン
　　　　　　　　　　　　　ー　ツイート

広告はAPI上ではPROMOTED_TWEETという名前で、遷移先URLはTWEETにあるのでそれとも結合する必要があります。

そのため、他の媒体ではすべてのデータを結合したものをBigQueryに上げればよかったものの、X広告においてはそれぞれのデータをBigQueryにあげてBigQuery上で結合する必要があります。

ここでややこしさに拍車を書けるのがActive Entitiesという仕組みです。

X広告は指定した日付範囲の任意のディメンジョンのメトリックを直接取得するといったことはできず、指定した日付範囲にアクティブだったキャンペーンや広告グループ、広告のIDを取得するAPIでそれぞれのIDを取得してそれを使ってメトリックを取得する必要があります。

処理の流れとしてはこんな感じです。

1. 指定日付範囲に有効だった広告のIDを取得
1. メトリック取得APIに広告のIDを20件ずつ渡してデータ取得
1. レスポンスのJSONを縦横変換してJsonlを作成
1. キャンペーンや広告グループなどを洗い替え

もうややこしすぎて他の媒体とは一線を画しています。

私が使い方を間違えていて実はもっと良い方法があるのかもしれませんがもうやりたくないです:innocent:

# 終わりに

主観マシマシでしたが、私が広告APIをそれぞれ触った時に感じたことを書いてみました。

Google広告APIは申請系はめちゃくちゃ遅かったでしたが使い勝手やドキュメントは非常に良いなど面白い学びがありました。

だいぶ苦労はしましたがなんだかんだ面白かったです。

たまにはこういったネタ記事も投下していこうかと思いますので今後ともよろしくお願いします！


# Oh my teethについて
Oh my teethでは未来の歯科体験を創るために日々活動しています。

Techチームではより良いユーザー体験を提供するべく、Webフロントエンドからバックエンド、スマホアプリに機械学習モデルなど、さまざまなプロダクトを開発しています。

一緒に未来の歯科体験を創りませんか？興味がある方は是非こちらを確認してください。

https://oh.careers/

カジュアル面談も可能なので気軽に応募してみてください！

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3192685/0138b492-e02b-852e-61fa-fc065b53d285.png" width="450" />