Instagramユーザーインサイト

Instagramユーザーについてのソーシャルインタラクション指標を表します。

作成

この操作はサポートされていません。

読み取り

GET /{ig-user-id}/insights

IGユーザーについてのインサイトを返します。

制限

• follower_count、online_followers、audience_*では、フォロワーが100人以下のIGユーザーは省かれます。
• online_followers指標のインサイトデータは、過去30日間についてのみ利用できます。
• リクエストしたインサイトデータが存在しない場合、または現在アクセスできない場合、APIは個別の指標で0ではなく空のデータセットを返します。
• 利用者層データ指標で返されるのは、上位45件のみです(例: audience_cityの場合、フォロワー数の点で上位45の都市)。
• 利用者層データ指標の計算で使われるのは、利用者層データがある閲覧者だけです。
• 利用者層データ指標値を合計しても、フォロワー数より少ない場合があります(前の項目を参照)。
• audience_*指標において、sinceとuntilの範囲パラメーターはサポートされていません。
• 指標計算に使用されるデータは、最大で48時間遅れている可能性があります。

要件

リクエストの構文

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &since={since}
  &until={until}
  &access_token={access-token}

パスパラメーター

クエリ文字列パラメーター

指標と期間

lifetime期間がサポートされている指標では、24時間の期間からなる配列で返されます。各期間はUTC−07:00で終了します。audience_*指標は、sinceとuntilの範囲パラメーターをサポートしません。

範囲

このエッジは時間ベースのページ割りをサポートしているため、Unixタイムスタンプを使ってsinceパラメーターとuntilパラメーターを含めることにより範囲を定義できます。例えば、28日分のインプレッションを取得するには(過去10日間の毎日)、10日前と今日のUnixタイムスタンプを生成し、それらをsinceパラメーターとuntilパラメーターに割り当ててリクエストに含めます:

metric=impressions&period=days_28&since=1501545600&until=1502493720

sinceパラメーターとuntilパラメーターには指定された日付が含まれるため、まだ終了していない日(つまり今日)が範囲に含まれる場合は、その日に何度かクエリを行うとそのたびに返される値が増える可能性があります。sinceパラメーターとuntilパラメーターを指定しない場合、APIのデフォルトである2日間(昨日から今日まで)が使用されます。

リクエストの例

curl -X GET \
  'https://graph.facebook.com/v19.0/17841405822304914/insights?metric=impressions,reach,profile_views&period=day&access_token=IGQVJ...'

応答の例

{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 4,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 66,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "Total number of times this profile has been seen",
      "id": "17841400008460056/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 3,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 36,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen this profile",
      "id": "17841400008460056/insights/reach/day"
    },
    {
      "name": "profile_views",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 2,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Profile Views",
      "description": "Total number of unique accounts that have viewed this profile within the specified period",
      "id": "17841400008460056/insights/profile_views/day"
    }
  ]
}

上記のリクエスト例ではsinceパラメーターとuntilパラメーターが指定されていないため、APIはデフォルト範囲の2日間のデータを返しています。各日付はISO 8601形式の0オフセットUTCタイムスタンプで示され、end_timeプロパティに割り当てられています。

end_timeプロパティはデータセットの過去参照限界日を示します。この値より古いデータはデータセットの計算に含まれません。

更新

この操作はサポートされていません。

削除

この操作はサポートされていません。

新しい指標

リクエストの構文

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &timeframe={timeframe}
  &metric_type={metric-type}
  &breakdown={breakdown}
  &since={since}
  &until={until}
  &access_token={access-token}

パスパラメーター

クエリ文字列パラメーター

内訳

metric_type=total_valueをリクエストする場合、1つ以上の内訳を指定することもできます。その場合、結果は、指定された内訳に基づいて、より細かいセットに分割されます。値は次のいずれかです。

• contact_button_type — 閲覧者がタップまたはクリックしたプロフィールUIコンポーネント別に結果を分割します。応答値は次のいずれかです。

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type — フォロワーかフォロワー以外かで結果を分割します。応答値は次のいずれかです。

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type — 閲覧者がアプリユーザーのメディアを閲覧または操作したサーフェス別に、結果を分割します。応答値は次のいずれかです。

  • AD
  • FEED
  • REELS
  • STORY

どの指標が内訳と互換性があるのかを調べるには、指標の表をご覧ください。内訳をサポートしない指標をリクエストすると、APIからはエラー("An unknown error has occurred.")が返されるため、単一のクエリで複数の指標をリクエストする場合には十分に注意してください。

metric_type=time_seriesをリクエストしても、応答に内訳は含められません。

指標のタイプ

結果の集計方法として、期間ごとに集計するか、それとも単純な合計(リクエストした場合は内訳を付けて)にするかを指定することができます。値は次のいずれかです。

• time_series — 期間ごとに結果を集計するよう、APIに対して指示します。期間をご覧ください。
• total_value — 単純な合計として結果を返すよう、APIに対して指示します。リクエストに内訳が含まれている場合、結果セットは具体的な内訳によってさらに細かく分類されます。内訳をご覧ください。

期間

結果集計時に使用する時間枠をAPIに対して指示します。インタラクション関連の指標でのみ有効です。

時間枠

利用者層関連の指標をリクエストする際に、データをどこまでさかのぼるかをAPIに対して指示します。この値により、sinceとuntilのパラメーターはオーバーライドされます。

範囲

sinceとuntilのパラメーターにUNIXタイムスタンプを割り当てて、範囲を定義します。APIが結果に含めるのは、この範囲内に作成されたデータのみになります(両端を含む)。これらのパラメーターを含めない場合、APIは24時間前からのデータを採用します。

利用者層データ関連の指標の場合、これらの値はtimeframeパラメーターによりオーバーライドされます。時間枠をご覧ください。

指標

インタラクションの指標

利用者層データの指標

応答

クエリ結果を含むJSONオブジェクト。使用されたクエリ仕様に基づいて、結果には以下のデータが含まれることがあります。

{
  "data": [
    {
      "name": "{data}",
      "period": "{period}",
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value": {value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{key-1}",
              "{key-2",
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "{value-1}",
                  "{value-2}",
                  ...
                ],
                "value": {value},
                "end_time": "{end-time}"
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ],
  "paging": {
    "previous": "{previous}",
    "next": "{next}"
  }
}

応答の内容

インタラクションの指標リクエストの例

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..."

インタラクション指標の応答の例

{
  "data": [
    {
      "name": "reach",
      "period": "day",
      "title": "Accounts reached",
      "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.",
      "total_value": {
        "value": 224,
        "breakdowns": [
          {
            "dimension_keys": [
              "media_product_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "CAROUSEL_CONTAINER"
                ],
                "value": 100
              },
              {
                "dimension_values": [
                  "POST"
                ],
                "value": 124
              }
            ]
          }
        ]
      },
      "id": "17841405309211844/insights/reach/day"
    }
  ],
  "paging": {
    "previous": "https://graph.face...",
    "next": "https://graph.face..."
  }

利用者層データ指標のリクエストの例

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..."

利用者層データ指標の応答の例

{
  "data": [
    {
      "name": "engaged_audience_demographics",
      "period": "lifetime",
      "title": "Engaged audience demographics",
      "description": "The demographic characteristics of the engaged audience, including countries, cities and gender distribution.",
      "total_value": {
        "breakdowns": [
          {
            "dimension_keys": [
              "timeframe",
              "country"
            ],
            "results": [
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "AR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "RU"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "LA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "IQ"
                ],
                "value": 2
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MX"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "FR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "ES"
                ],
                "value": 3
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "NL"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "TR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "US"
                ],
                "value": 7
              }
            ]
          }
        ]
      },
      "id": "17841401130346306/insights/engaged_audience_demographics/lifetime"
    }
  ]
}