FacebookページAPI

ページのインサイトを取得する

このガイドでは、Facebookページの指標を取得する方法を説明します。Facebookページに「いいね！」をした人の総数や、ページのストーリーをシェアした人の数を取得できます。

On March 14, 2024, a number of the Page Insights metrics were deprecated for all API versions. The API returns an invalid metric error when calling any of these metrics. Read our blog to learn more.

制限

  • 公開されているページの指標データは、Facebookによって2年間保存されます。
  • 公開されていないページの指標データは、5日間しか保存されません。
  • sinceとuntilで1日の指標を見る際、最初、end_timeの値は、since日付のデータが含まれるよう、sinceに指定された日付プラス1となります。たとえば、sinceを2018年1月1日に設定すると、end_timeは2018年1月2日の8:00 GMTとなります。

開始する前に

単一指標の取得

GETリクエストを/{page-id}/insights/{metric-name}エンドポイントに送信します。

curl -i -X GET "https://graph.facebook.com/{page-id}/insights/page_impressions_unique
  ?access_token={page-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "data": [
    {
      "name": "page_impressions_unique",
      "period": "day",
      "values": [
        {
          "value": 66226,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 78037,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Daily Total Reach",
      "description": "Daily: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/day"
    },
    {
      "name": "page_impressions_unique",
      "period": "week",
      "values": [
        {
          "value": 202229,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 206982,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Weekly Total Reach",
      "description": "Weekly: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/week"
    },
    {
      "name": "page_impressions_unique",
      "period": "days_28",
      "values": [
        {
          "value": 427380,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 432909,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "28 Days Total Reach",
      "description": "28 Days: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/days_28"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique&since=1583568000&until=1583737200",
    "next": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique&since=1583910000&until=1584082800"
  }
}

複数指標の取得

metricフィールドを指定して、GETリクエストを/{page-id}/insightsエンドポイントに送信します。

curl -i -X GET "https://graph.facebook.com/{page-id}/insights
  ?metric=page_impressions_unique,page_impressions_paid
  &access_token={page-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "data": [
    {
      "name": "page_impressions_unique",
      "period": "day",
      "values": [
        {
          "value": 60,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 50,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "Daily Total Reach",
      "description": "Daily: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "PAGE_ID/insights/page_impressions_unique/day"
    },
    {
      "name": "page_impressions_paid",
      "period": "day",
      "values": [
        {
          "value": 8,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 10,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "Daily Paid Impressions",
      "description": "Daily: The number of times any post or story content from your Page or about your Page entered a person's screen through paid distribution such as an ad. (Total Count)",
      "id": "PAGE_ID/insights/page_impressions_paid/day"
    },
    {
      "name": "page_impressions_unique",
      "period": "week",
      "values": [
        {
          "value": 40,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 50,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "Weekly Total Reach",
      "description": "Weekly: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "PAGE_ID/insights/page_impressions_unique/week"
    },
    {
      "name": "page_impressions_paid",
      "period": "week",
      "values": [
        {
          "value": 50,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 106,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "Weekly Paid Impressions",
      "description": "Weekly: The number of times any post or story content from your Page or about your Page entered a person's screen through paid distribution such as an ad. (Total Count)",
      "id": "PAGE_ID/insights/page_impressions_paid/week"
    },
    {
      "name": "page_impressions_unique",
      "period": "days_28",
      "values": [
        {
          "value": 110,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 10,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "28 Days Total Reach",
      "description": "28 Days: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "PAGE_ID/insights/page_impressions_unique/days_28"
    },
    {
      "name": "page_impressions_paid",
      "period": "days_28",
      "values": [
        {
          "value": 120,
          "end_time": "2024-03-11T07:00:00+0000"
        },
        {
          "value": 20,
          "end_time": "2024-03-12T07:00:00+0000"
        }
      ],
      "title": "28 Days Paid Impressions",
      "description": "28 days: The number of times any post or story content from your Page or about your Page entered a person's screen through paid distribution such as an ad. (Total Count)",
      "id": "PAGE_ID/insights/page_impressions_paid/days_28"
    }
  ],
...

ページ投稿の指標の取得

metricフィールドを指定して、GETリクエストを/{page-post-id}/insightsエンドポイントに送信します。

curl -i -X GET "https://graph.facebook.com{page-post-id}/insights
  ?metric=post_reactions_like_total,post_reactions_love_total,post_reactions_wow_total
  &access_token={page-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "data": [
    {
      "name": "post_reactions_like_total",
      "period": "lifetime",
      "values": [
        {
          "value": 226
        }
      ],
      "title": "Lifetime Total Like Reactions of a post.",
      "description": "Lifetime: Total like reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_like_total/lifetime"
    },
    {
      "name": "post_reactions_love_total",
      "period": "lifetime",
      "values": [
        {
          "value": 17
        }
      ],
      "title": "Lifetime Total Love Reactions of a post.",
      "description": "Lifetime: Total love reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_love_total/lifetime"
    },
    {
      "name": "post_reactions_wow_total",
      "period": "lifetime",
      "values": [
        {
          "value": 1
        }
      ],
      "title": "Lifetime Total wow Reactions of a post.",
      "description": "Lifetime: Total wow Reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_wow_total/lifetime"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{page-post-id}/insights?access_token={page-access-token}b&pretty=0&metric=post_reactions_like_total%2Cpost_reactions_love_total%2Cpost_reactions_wow_total&since=1583568000&until=1583737200",
    "next": "https://graph.facebook.com/{page-post-id}/insights?access_token={page-access-token}&pretty=0&metric=post_reactions_like_total%2Cpost_reactions_love_total%2Cpost_reactions_wow_total&since=1583910000&until=1584082800"
  }
}

動画CMのインプレッション数の取得

追加要件

GETリクエストを/{page-id}エンドポイントに送信して、ページの1日の動画CMのインプレッション数を取得します。

curl -i -X GET \
  "https://graph.facebook.com/{page-id}/insights
    ?metric=page_daily_video_ad_break_ad_impressions_by_crosspost_status
    &period=day
    &since=2017-12-10
    &until=2017-12-14"

成功すると、アプリは次の応答を受け取ります。

{
  "data": [
    {
      "name": "page_daily_video_ad_breaks_ad_impressions_by_crosspost_status",
      "period": "day",
      "values": [
        {
          "value": {
          "crossposted": 27584,
          "owned": 692730
          },
          "end_time": "2017-12-11T08:00:00+0000"
          },
          {
            "value": {
              "owned": 757456,
              "crossposted": 20593
            },
            "end_time": "2017-12-12T08:00:00+0000"
          },
          {
            "value": {
              "owned": 690092,
              "crossposted": 15372
            },
            "end_time": "2017-12-13T08:00:00+0000"
          }
        ],
        "title": "Daily page level videos ad impression",
        "description": "Number of times an ad was shown during ad breaks in your Page's videos, by distribution type (page_owned and crossposted).",
        "id": "{page-id}/insights/page_daily_video_ad_break_ad_impressions_by_crosspost_status/day"
      }
...

ページ投稿の1日の動画CMインプレッション数の取得

metricフィールドを指定して、GETリクエストを/{page-post-id}/insightsエンドポイントに送信します。

curl -i -X GET "https://graph.facebook.com/{page-post-id}/insights
  ?metric=post_video_ad_break_ad_impressions
  &period=day
  &since=2017-12-10
  &until=2017-12-14
  &access_token={page-access-token}"

成功すると、アプリは次の応答を受け取ります。

{ 
  "data": [
    {
      "name": "total_video_ad_break_ad_impressions",
      "period": "day",
      "values": [
        {
          "value": 2612,
          "end_time": "2017-12-11T08:00:00+0000"
        },
        {
          "value": 1038,
          "end_time": "2017-12-12T08:00:00+0000"
        },
        {
          "value": 818,
          "end_time": "2017-12-13T08:00:00+0000"
        },
        {
          "value": 553,
          "end_time": "2017-12-14T08:00:00+0000"
        }
      ],
      "title": "Daily Video Ad Break Ad Impressions",
      "description": "Number of times an ad was shown during your video ad breaks.",
      "id": "{video-id}/video_insights/total_video_ad_break_ad_impressions/day"
    }
...

ページ投稿の通算動画CMインプレッション数の取得

curl -i -X GET "https://graph.facebook.com/{page-post-id}/insights
  ?metric=post_video_ad_break_ad_impressions
  &period=lifetime
  &access_token={page-access-token}"

成功すると、アプリは次の応答を受け取ります。

{
  "data": [
    {
      "name": "total_video_ad_break_ad_impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 55468
        }
      ],
      "title": "Lifetime Video Ad Break Ad Impressions",
      "description": "Number of times an ad was shown during your video ad breaks.",
      "id": "{video-id}/video_insights/total_video_ad_break_ad_impressions/lifetime"
    }
...

よくあるエラーコード

エラーコードエラーメッセージ説明

なし

空のデータセットが返されます。

このエンドポイントにアクセスするには、read_insightsアクセス許可が必要です。

100

「(#100) 値は有効なインサイト指標でなければなりません」

スペルや構文に問題がある可能性があります。

3001、"error_subcode": 1504028

「取得する指標が指定されていません。取得する指標を1つ以上指定して、もう一度試してください。」

metricパラメーターを使用する場合は、少なくとも1つの指標がクエリに含まれている必要があります。

参考情報