広告インサイトAPI

広告インサイトAPIは、Meta広告のパフォーマンスデータと統計情報を提供します。柔軟なレポートオプションにより、リクエストをカスタマイズして、Meta広告マネージャで利用可能なほぼすべての指標を取得できます。

はじめに

広告インサイトAPIにアクセスするには、次のものが必要です。

アプリ。(詳しくは、Metaアプリ開発をご覧ください。)
ads_readアクセス許可。(詳しくは、アクセス許可および認証をご覧ください。)

また、興味のあるアクションをトラッキングするよう広告を設定する必要もあります。そのために、コンバージョンAPIやMetaピクセルなどのツールを使うことができます。

広告インサイトAPIを呼び出す

広告インサイトAPIは、すべての広告オブジェクトに紐づくエッジとして利用できます。(Metaの広告階層について詳しくは、こちらをご覧ください。)

リソース	取得できるインサイト
`/{ad-account-id}/insights`	広告アカウントのインサイト
`/{campaign-id}/insights`	広告キャンペーンのインサイト
`/{ad-set-id}/insights`	広告セットのインサイト
`/{ad-id}/insights`	広告のインサイト

デフォルトでは、GETリクエストは広告オブジェクトの基本的な指標を返します。これは通常、過去30日間のものです。

リクエストの例

curl -G \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/v26.0/<CAMPAIGN_ID>/insights"

応答の例:

{
  "data": [
    {
      "account_id": "<AD_ACCOUNT_ID>",
      "campaign_id": "<CAMPAIGN_ID>",
      "date_start": "2025-03-14",
      "date_stop": "2025-04-12",
      "impressions": "361324",
      "spend": "5339.5"
    }
  ],
  "paging": {
    "cursors": {
    "before": "MAZDZD",
    "after": "MAZDZD"
    }
  }
}

リクエストをカスタマイズする

リクエストの3つの主な構成要素である、パラメーター(期間やアトリビューションウィンドウなどを指定)、フィールド(指標)、内訳を活用することで、さらに具体的なデータを取得できます。例えば、キャンペーンの過去7日間における性別ごとのクリック数(すべて)を知りたい場合、以下を含めることができます。

パラメーター: date_preset=last_7d
フィールド: clicks
内訳: gender

リクエストの例

curl -G \ -d "date_preset=last_7d" \ -d "fields=clicks" \ -d "breakdowns=gender" \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/v26.0/<CAMPAIGN_ID>/insights"

応答の例

{
  "data": [
    {
      "clicks": "7346",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "female"
    },
    {
      "clicks": "3788",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "male"
    },
    {
      "clicks": "79",
      "date_start": "2025-04-06",
      "date_stop": "2025-04-12",
      "gender": "unknown"
    },
  ],
  "paging": {
    "cursors": {
    "before": "MAZDZD",
    "after": "MAZDZD"
    }
  }
}

詳しくはこちら

広告インサイトAPIは強力なツールです。以下の関連ドキュメントを確認して、APIの機能を最大限に活用する方法を学びましょう。

パラメーターとフィールド
指標
内訳
非同期リクエスト
制限とベストプラクティス
コンバージョンレポート、製品レベルのレポート、マーケティングミックスモデルに関する詳細なガイド

各広告オブジェクトのインサイトエッジに関する自動生成のリファレンスドキュメントも参照できます。

広告インサイトAPIからのデータを自社のソリューションに組み込む場合は、Metaプラットフォーム利用規約とマーケティングAPIの開発者ポリシーもご確認ください。