Статистика объекта Instagram User

Представляет метрики социального взаимодействия для объекта Instagram User.

Создание

Эта операция не поддерживается.

Чтение

GET /{ig-user-id}/insights

Возвращает статистику для объекта IG User.

Ограничения

• Метрики follower_count, online_followers и все метрики audience_* недоступны для пользователей IG User, у которых менее 100 подписчиков.
• Статистика для метрики online_followers доступна только за последние 30 дней.
• Если запрашиваемые данные статистики на текущий момент не существуют или недоступны, вместо значений 0 для каждой отдельной метрики API возвращает пустой набор данных.
• Для демографических метрик возвращаются только 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), можно сгенерировать метки времени Unix для моментов 10 дней назад и сегодня, присвоить их параметрам since и until и добавить в запрос:

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

Параметры since и until работают включительно, поэтому, если диапазон содержит день, который ещё не закончился (т. е. сегодня), то последующие запросы в течение дня могут возвращать постепенно возрастающие значения. Если параметры since и until не указаны, API по умолчанию использует двухдневный диапазон: со вчера по сегодня.

Пример запроса

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 возвращает данные в диапазоне по умолчанию — за два дня. Каждый день идентифицируется меткой времени UTC в формате ISO 8601 с нулевым смещением, назначенным свойству 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.

Диапазон

Присваивание меток времени 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"
    }
  ]
}