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 및 untilrange 매개변수를 지원하지 않습니다.
• 지표를 계산하는 데 사용한 데이터는 최대 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 및 untilrange 매개변수를 지원하지 않습니다.

범위

이 에지는 시간 기반 페이지 매김을 지원하므로 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 타임스탬프와 오프셋 0으로 식별되며, 이는 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 — 사용자가 탭하거나 클릭한 프로필 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 매개변수를 재정의합니다.

범위

UNIX 타임스탬프를 since 및 until 매개변수에 할당하여 범위를 정의합니다. 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"
    }
  ]
}