Instagram 用戶洞察報告

代表 Instagram 用戶的社交互動衡量數據。

建立

不支援這項操作。

讀取

GET /{ig-user-id}/insights

傳回 Instagram 用戶的洞察報告。

限制

• follower_count、online_followers、和所有 audience_* 衡量數據不可用於追蹤者少於 100 人的 Instagram 用戶。
• 您只能查看過去 30 天的 online_followers 衡量數據的洞察報告數據。
• 如果您正在要求的洞察報告資料不存在或者目前無法使用，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範圍參數。

範圍

此關係連線支援基於時間的分頁，因此您可以在其中加入 since 和 until 參數，並使用 Unix 時戳定義範圍。例如，如要獲取 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"
    }
  ]
}