Insights de usuário do Instagram

Representa as métricas de interação social sobre um usuário do Instagram.

Criação

Esta operação não é compatível.

Leitura

GET /{ig-user-id}/insights

Retorna insights sobre um usuário do Instagram.

Limitações

• As métricas follower_count, online_followers e todas as métricas audience_* não estão disponíveis para usuários do Instagram com menos de 100 seguidores.
• Os dados de insights da métrica online_followers estão disponíveis apenas para os últimos 30 dias.
• Se os dados de insights solicitados não existirem ou estiverem indisponíveis, a API retornará um conjunto vazio para as métricas individuais, em vez de 0.
• Para métricas demográficas, apenas os 45 resultados de melhor desempenho serão retornados (por exemplo, no caso de audience_city, poderão ser retornadas até 45 cidades com os maiores números de seguidores).
• Somente os visualizadores sobre quem tivermos dados demográficos serão usados nos cálculos de métricas desse tipo.
• A soma dos valores de métricas demográficas poderá resultar em um valor menor que a contagem de seguidores (confira o item anterior).
• As métricasaudience_* não são compatíveis com os parâmetros de intervalosince e until.
• Pode haver até 48 horas de atraso nos dados usados para calcular métricas.

Requisitos

Sintaxe da solicitação

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

Parâmetros de caminho

Parâmetros da string de consulta

Métricas e períodos

Para métricas compatíveis com períodos lifetime, os resultados serão retornados em uma matriz de períodos de 24 horas que terminam às 7:00 UTC. As métricas audience_* não são compatíveis com os parâmetros de intervalosince e until.

Intervalo

Esta borda aceita paginação com base no tempo. Assim, é possível incluir os parâmetros since e until com registros de data e hora do Unix para definir um intervalo. Por exemplo, para obter impressões para 28 dias (cada dia dos últimos 10), é possível gerar registros de data e hora do Unix referentes a 10 dias atrás e a hoje, atribuí-los aos parâmetros since e until e incluí-los na solicitação:

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

Os parâmetros since e until são inclusivos. Por isso, se o intervalo incluir um dia que ainda não terminou (ou seja, hoje), as próximas consultas durante o dia poderão retornar valores maiores. Se você não incluir os parâmetros since e until, a API usará um intervalo de dois dias por padrão: de ontem para hoje.

Exemplo de solicitação

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

Exemplo de resposta

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

Observe que o exemplo de solicitação acima não incluiu os parâmetros since e until. Por conta disso, a API retornou dados para um intervalo padrão de dois dias. Cada dia é identificado por um registro de data e hora UTC formatado de acordo com a norma ISO 8601 com zero deslocamento, que foi atribuído a uma propriedade end_time.

A propriedade end_time indica a data-limite do conjunto de dados. Os dados mais antigos que esse valor não serão incluídos no cálculo.

Atualização

Esta operação não é compatível.

Exclusão

Esta operação não é compatível.

Novas métricas

Sintaxe da solicitação

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}

Parâmetros de caminho

Parâmetros da string de consulta

Detalhamento

Se você solicitar metric_type=total_value, também será possível especificar um ou mais detalhamentos, e os resultados serão divididos em conjuntos menores com base no detalhamento especificado. Os valores podem ser os seguintes:

• contact_button_type – Detalha os resultados por componente de interface do usuário do perfil em que os visualizadores tocaram ou clicaram. Estes são os possíveis valores de resposta:

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type – Detalha os resultados por seguidores ou não seguidores. Estes são os possíveis valores de resposta:

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type – Detalha os resultados pela superfície em que os visualizadores viram ou interagiram com a mídia do usuário do app. Estes são os possíveis valores de resposta:

  • AD
  • FEED
  • REELS
  • STORY

Consulte a tabela Métricas para determinar as métricas que são compatíveis com um detalhamento. Se você solicitar uma métrica que não seja compatível com um detalhamento, a API retornará um erro ("An unknown error has occurred."). Por isso, tenha cuidado ao solicitar várias métricas em uma única consulta.

Se você solicitar metric_type=time_series, os detalhamentos não serão incluídos na resposta.

Tipo de métrica

Você pode escolher como deseja que os resultados sejam agregados, por período ou total simples (com detalhamentos, caso solicitado). Os valores podem ser os seguintes:

• time_series – Instrui a API a agregar os resultados por período. Consulte Período.
• total_value – Instrui a API a retornar os resultados como um total simples. Se houver detalhamentos incluídos na solicitação, o conjunto de resultados será dividido por detalhamentos específicos. Consulte Detalhamento.

Período

Informa à API o intervalo de tempo que deve ser usado ao agregar resultados. Compatível somente com métricas relacionadas à interação.

Intervalo de tempo

Informa à API o ponto mais antigo onde verificar dados ao solicitar métricas relacionadas a dados demográficos. Esse valor substitui os parâmetros since e until.

Intervalo

Atribui registros de data e hora do UNIX aos parâmetros since e until para definir um intervalo. A API incluirá apenas dados criados nesse intervalo (inclusive). Se você não incluir esses parâmetros, a API fará a verificação das últimas 24 horas.

Para métricas relacionadas a dados demográficos, o parâmetro timeframe substitui esses valores. Consulte Intervalo de tempo.

Métricas

Métricas de interação

Métricas de dados demográficos

Resposta

Um objeto JSON que contém os resultados da sua consulta. Os resultados podem incluir os seguintes dados, com base nas especificações da sua consulta:

{
  "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}"
  }
}

Conteúdo da resposta

Exemplo de solicitação de métrica de interação

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..."

Exemplo de resposta de métrica de interação

{
  "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..."
  }

Exemplo de solicitação de métrica demográfica

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..."

Exemplo de resposta de métrica demográfica

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