インサイトAPI

広告の統計情報を取得するための、一貫性のある単一のインターフェイスを提供します。

内訳 - グループ分けした結果
アクションの内訳 - アクションの内訳から応答を把握します。
非同期ジョブ - 結果が多くなるリクエストには、非同期ジョブを使用します
制限とベストプラクティス - 呼び出しの制限、フィルタリング、ベストプラクティス。

広告のパフォーマンスに関するデータを収集する前に、調べたい指標がトラッキングされるように広告を設定する必要があります。そのためには、URLタグ、Metaピクセル、コンバージョンAPIを使用できます。

iOS 14.5に関する最新情報

Appleの新しいポリシーに対応して、アトリビューションウィンドウに影響する重要な変更を発表します。

Apple iOS 14.5の要件がFacebook広告に与える影響については、ビジネスヘルプセンターの記事と更新履歴をご確認ください。

影響を受けるエンドポイント

GET /{ad-account-id}/insights
GET /{ad-id}/insights
GET /{ad-set-id}/insights
GET /{campaign-id}/insights
POST /{ad-account-id}/insights
POST /{ad-id}/insights
POST /{ad-set-id}/insights
POST /{campaign-id}/insights

はじめに

以下が必要です。

ads_readアクセス許可。
アプリ。詳しくは、Metaアプリ開発をご覧ください。

キャンペーンの統計データ

キャンペーンの過去7日間のパフォーマンスに関する統計データを取得する手順は、次のとおりです。

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

詳しくは、広告インサイトリファレンスをご覧ください。

呼び出しの実行

インサイトAPIはエッジとしてあらゆる広告オブジェクトで利用できます。

APIメソッド
`act_<AD_ACCOUNT_ID>/insights`
`<CAMPAIGN_ID>/insights`
`<ADSET_ID>/insights`
`<AD_ID>/insights`

リクエスト

fieldsパラメーターでコンマ区切りリストを使用して、特定のフィールドを次のようにリクエストできます。例:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_OBJECT_ID/insights"

応答

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

レベル

定義済みのオブジェクトレベルで結果を集計します。これによりデータが自動的に重複します。

リクエスト

例として、キャンペーンの広告レベルのインサイトを取得します。

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/CAMPAIGN_ID/insights"

応答

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

すべての広告オブジェクトに対して、リクエストしたレベルのアクセス許可を持っていない場合は、インサイトを呼び出してもデータは返されません。例えば、levelをadに設定してインサイトをリクエストしたときに、1つ以上の広告オブジェクトに対するアクセス許可を広告アカウントが持っていない場合、このAPI呼び出しでは許可エラーが返されます。

アトリビューションウィンドウ

iOS 14以降に関する最新情報

action_attribution_windowsが設定されていない場合、デフォルトのアトリビューション値は7d_clickと1d_viewです。施行が開始されると、28日間のビュー数は提供されなくなり、空のデータが返されます。
28日間の期間の値を持つアクティブでない従来の広告については、このデータが返されます。
施行後、デフォルトまたはアカウントレベルのウィンドウは7日間になります。
use_account_attribution_settingフィールドは廃止されます。代わりにそのようなリクエストは、デフォルトが7d_clickと1d_viewのaction_attribution_windowsに切り替わります。

iOS 14により生じた変更について詳しくは、重要な変更の更新履歴をご覧ください。

コンバージョンアトリビューションウィンドウは、イベントがMetaアプリ上の広告をアトリビューション分析する期間を定義するタイムフレームを提供します。背景情報については、Metaビジネスヘルプセンター、アトリビューションウィンドウについてをご覧ください。コンバージョンイベントが発生したときに起きたアクションを、過去1日および7日の期間で測定します。異なるアトリビューションウィンドウにアトリビューションされたアクションを表示するには、/{ad-account-id}/insightsにリクエストを実行します。action_attribution_windowsを指定しなかった場合、Facebookによって7d_clickが使用され、valueで指定されます。

例えば、action_attribution_windowsが指定され、「value」が7d_clickのアトリビューションウィンドウで固定されます。act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view']にリクエストを実行すると、次のような結果が得られます。

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

フィールド拡張機能

フィールドをノードレベルでリクエストし、フィールド拡張機能でフィールドごとに次のように指定します。

リクエスト

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_ID"

応答

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

並べ替え

結果を並べ替えるには、sortパラメーターを{fieldname}_descendingまたは{fieldname}_ascendingとともに次のように指定します。

リクエスト

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_SET_ID/insights"

応答


{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

広告ラベル

ラベルの名前が同じものの統計情報です。広告オブジェクトレベルで1つの値に集計されます。詳しくは、広告ラベルリファレンスをご覧ください。

リクエスト

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_OBJECT_ID/insights"

応答

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

クリックの定義

現在Metaから提供されているクリックに関する指標の詳細については、下記にある、それぞれの定義と使用方法をご覧ください。

リンククリック、actions:link_click - Meta内外のリンク先やエクスペリエンスを選択するための広告リンクがクリックされた回数です。広告ヘルプセンター、リンククリックをご覧ください
クリック(すべて)、clicks - この指標は、広告でのさまざまなタイプのクリックをカウントします。これには、広告コンテナ、他のリンク先へのリンク、拡張された広告エクスペリエンスへのリンクとの、特定のタイプのインタラクションが含まれます。広告主様向けヘルプセンターのクリック(すべて)をご覧ください

削除されたオブジェクトとアーカイブされたオブジェクト

広告ユニットはDELETEDまたはARCHIVEDになります。削除またはアーカイブされたオブジェクトの統計データは、その親オブジェクトをクエリしたときに表示されます。つまり、impressionsを広告セットレベルでクエリした場合は、広告が削除またはアーカイブされているかどうかにかかわらず、結果にはそのセット内のすべての広告のimpressionsが含まれます。広告オブジェクトの保存と取得のベストプラクティスもご覧ください。

しかし、クエリでフィルターを使っている場合、ステータスフィルターがデフォルトで適用されて、アクティブなオブジェクトのみが返されます。結果的に、親ノードの統計情報の合計が子の統計情報よりも大きくなる場合があります。

ただし、追加のfilteringパラメーターを指定すると、親ノードのARCHIVEDオブジェクトの統計情報を取得できます。

リクエスト

広告アカウントのリストにあるすべてのARCHIVED広告の統計情報を1つずつ取得するには、次を実行します。

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/insights/"

応答

この応答ではアーカイブオブジェクトのみが返されます。

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

削除オブジェクトインサイト

IDがわかる場合、またはad.effective_statusフィルターを使用すれば、削除済みオブジェクトのインサイトをクエリできます。

リクエスト

例えば、広告セットIDがわかる場合、次のようにします。

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_SET_ID"

この例では、ad.effective_statusを使用して次のようにクエリします。

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

応答

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

トラブルシューティング

タイムアウト

このエンドポイントでのエラーの原因としてよくみられるのが、リクエストが多過ぎる、またはタイムアウトです。

/GETまたは同期リクエストでは、メモリ不足やタイムアウトのエラーが発生することがあります。
/POSTまたは同期リクエストでは、タイムアウトエラーが発生することがあります。非同期リクエストの場合は、再試行を含むリクエストが完了するまでに最大で1時間かかることがあります。多数の広告レベルオブジェクトの大量のデータを取得するようなクエリの場合に、エラーが発生することがあります。

推奨事項

クエリが失敗するという明示的な制限があるわけではありません。タイムアウトが発生した場合は、日付範囲などのフィルターを適用して、より小規模なクエリを実行してみてください。
ユニークデータに関する指標の算出には時間がかかります。ユニークデータに関する指標に対するクエリを別の呼び出しで実行すれば、非ユニークデータに関する指標のパフォーマンスが向上します。

レート制限

MetaインサイトAPIは、レート制限を設けることで、すべてのパートナーがレポート機能を快適に使用できるようにします。詳細と推奨事項については、インサイトAPIの制限とベストプラクティスをご覧ください。

広告マネージャとの不一致

APIのデフォルトの動作は、広告マネージャのデフォルトの動作とは異なります。広告マネージャと同じ動作にしたい場合は、フィールドuse_account_attribution_settingをtrueに設定してください。

詳しくはこちら

このAPIは、上のリストにないエンドポイントには対応していません。Metaのレポートを自社ソリューションに組み込む場合は、Metaプラットフォーム規約とマーケティングAPIの開発者ポリシーをご覧ください。