Instagram 用戶洞察報告

代表 Instagram 用戶的社群互動衡量指標。

建立

不支援執行此作業。

讀取

GET /{ig-user-id}/insights

傳回 IG 用戶的洞察報告。

限制

• 擁有不到 100 個粉絲的 IG 用戶沒有 follower_count、online_followers 和所有 audience_* 衡量指標。
• 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 格式化的零位移 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，也可以指定一或多個資料解析，並根據指定的資料解析將結果細分為較小的集合。可能的值如下：

• contact_button_type — 細分結果，排序依據是瀏覽者點按或點擊的個人檔案用戶介面元件。可能的回應值如下：

  • 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"
    }
  ]
}