Insights de usuarios de Instagram

Representa las métricas de interacción social de un usuario de Instagram.

Creación

Esta operación no es compatible.

Lectura

GET /{ig-user-id}/insights

Devuelve insights sobre un usuario de Instagram.

Limitaciones

• Los valores de follower_count, online_followers y todas las métricas de audience_* no están disponibles para los usuarios de IG con menos de 100 seguidores.
• Los datos de insights de la métrica online_followers solo están disponibles para los últimos 30 días.
• Si los datos de insights que solicitas no existen o no están disponibles actualmente, la API devolverá un conjunto de datos vacío en lugar de 0 para las métricas individuales.
• Las métricas demográficas solo devuelven los 45 elementos que presentan un mayor rendimiento (por ejemplo, para audience_city, pueden devolverse hasta 45 ciudades con el mayor número de seguidores).
• Solo los espectadores de los que tenemos datos demográficos se utilizan en los cálculos de métricas demográficas.
• La suma de valores de métricas demográficas puede dar lugar a un valor inferior al recuento de seguidores (consulta la viñeta anterior).
• Las métricasaudience_* no admiten los parámetros de intervalosince y until.
• Los datos utilizados para calcular métricas pueden retrasarse hasta 48 horas.

Requisitos

Sintaxis de la solicitud

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 ruta

Parámetros de la cadena de consulta

Métricas y periodos

Las métricas que admiten los periodos lifetime se devolverán en una matriz de periodos de 24 horas, con periodos que finalizan a la hora UTC −07:00. Las métricas audience_* no admiten los parámetros de intervalosince y until.

Intervalo

Este perímetro admite la paginación basada en tiempo, de modo que puedes incluir los parámetros since y until con marcas de tiempo UNIX para definir un intervalo. Por ejemplo, para obtener impresiones de 28 días (diarias de los últimos diez días), podrías generar marcas de tiempo UNIX de hace diez días y hoy, asignarlas a los parámetros since y until e incluirlas en la solicitud:

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

Los parámetros since y until son inclusivos, de modo que, si tu intervalo incluye un día que no ha terminado (p. ej., hoy), las consultas subsiguientes del día pueden devolver valores incrementados. Si no incluyes los parámetros since y until, el valor predeterminado de la API se establecerá en un intervalo de 2 días (de ayer a hoy).

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Ten en cuenta que el ejemplo de solicitud anterior no incluye los parámetros since y until, de modo que la API devolvió datos de un intervalo predeterminado de 2 días. Los días se identifican mediante una marca de tiempo UTC con formato ISO 8601 y un desplazamiento de cero, que se ha asignado a una propiedad end_time.

La propiedad end_time indica una fecha límite de retroactividad del conjunto de datos; los datos anteriores a este valor no se incluyen en el cálculo del conjunto de datos.

Actualización

Esta operación no es compatible.

Eliminar

Esta operación no es compatible.

Métricas nuevas

Sintaxis de la solicitud

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 ruta

Parámetros de la cadena de consulta

Desglose

Si solicitas metric_type=total_value, también puedes especificar uno o varios desgloses, de modo que los resultados se desglosarán en conjuntos más pequeños en función del desglose especificado. Los valores pueden ser los siguientes:

• contact_button_type: desglosa los resultados por el componente de la interfaz de usuario del perfil que los espectadores tocaron o en el que hicieron clic. Los valores de la respuesta pueden ser los siguientes:

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type: desglosa los resultados por seguidores o no seguidores. Los valores de la respuesta pueden ser los siguientes:

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type: desglosa los resultados por la superficie en la que los espectadores vieron el contenido multimedia del usuario de la aplicación o interactuaron con dicho contenido. Los valores de la respuesta pueden ser los siguientes:

  • AD
  • FEED
  • REELS
  • STORY

Consulta la tabla Métricas para determinar qué métricas son compatibles con un desglose. Si solicitas una métrica que no admite un desglose, la API devolverá un error ("An unknown error has occurred."), así que debes prestar atención al solicitar varias métricas en una única consulta.

Si solicitas metric_type=time_series, no se incluirán desgloses en la respuesta.

Tipo de métrica

Puedes indicar cómo quieres que se agreguen los resultados: por periodo de tiempo o como un simple total (con desgloses, si lo solicitas). Los valores pueden ser los siguientes:

• time_series: indica a la API que agregue los resultados por periodo de tiempo. Consulta Periodo.
• total_value: indica a la API que devuelva los resultados como un simple total. Si se incluyen desgloses en la solicitud, el conjunto de resultados se desglosará por los desgloses específicos. Consulta Desglose.

Periodo

Indica a la API qué periodo de tiempo usar al agregar resultados. Solo es compatible con las métricas relacionadas con la interacción.

Periodo de tiempo

Indica a la API la duración del periodo retrospectivo de consulta de datos al solicitar métricas relacionadas con la demografía. Este valor anula los parámetros since y until.

Intervalo

Asigna marcas de tiempo UNIX a los parámetros since y until para definir un intervalo. La API solo incluirá datos creados durante este intervalo (incluido). Si no incluyes estos parámetros, la API establecerá la duración del periodo retrospectivo en 24 horas.

En el caso de las métricas relacionadas con la demografía, el parámetro timeframe anula estos valores. Consulta Intervalo de tiempo.

Métricas

Métricas de interacción

Métricas demográficas

Respuesta

Objeto JSON que contiene los resultados de la consulta. Los resultados pueden incluir los siguientes datos, en función de las especificaciones de la 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}"
  }
}

Contenido de la respuesta

Ejemplo de solicitud de métricas de interacciones

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

Ejemplo de respuesta de métricas de interacciones

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

Ejemplo de solicitud de métricas demográficas

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

Ejemplo de respuesta de métricas demográficas

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