Statistiques utilisateurs et utilisatrices Instagram

Représente les indicateurs d’interaction sociale sur un·e Utilisateur·ice Instagram.

Création

Cette opération n’est pas prise en charge.

Lecture

GET /{ig-user-id}/insights

Renvoie les statistiques sur un·e Utilisateur·ice Instagram.

Limitations

• Le follower_count, le online_followers et tous les indicateurs audience_* ne sont pas disponibles pour les utilisateurs et utilisatrices Instagram ayant moins de 100 followers.
• Les données statistiques pour l’indicateur online_followers sont disponibles uniquement pour les 30 derniers jours.
• Si les données statistiques demandées n’existent pas ou sont actuellement indisponibles, l’API renvoie un ensemble de données vide au lieu de la valeur 0 pour les indicateurs individuels.
• Les indicateurs démographiques renvoient uniquement les 45 premiers résultats (par exemple, pour la valeur audience_city, les 45 premières villes avec le nombre le plus élevé de followers pourront être renvoyées).
• Seules les personnes pour lesquelles nous disposons de données démographiques sont utilisées dans les calculs des indicateurs démographiques.
• La somme des valeurs des indicateurs démographiques peut être inférieure au nombre de followers (voir le point précédent).
• Les indicateursaudience_* ne prennent pas en charge les paramètres de plagesince et until.
• Les données utilisées pour calculer les indicateurs peuvent avoir jusqu’à 48 heures de retard.

Conditions requises

Syntaxe de la requête

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

Paramètres du chemin

Paramètres de chaîne de requête

Indicateurs et périodes

Les résultats des indicateurs qui prennent en charge les périodes lifetime seront renvoyés en périodes de 24 heures se terminant à UTC−07:00. Les indicateurs audience_* ne prennent pas en charge les paramètres de plagesince et until.

Plage

Comme cette arête prend en charge la pagination en fonction du temps, vous pouvez inclure les paramètres since et until avec les horodatages Unix pour définir une plage. Par exemple, pour obtenir 28 jours d’impressions (chaque jour pour les 10 derniers jours), vous pouvez générer des horodatages Unix pour il y a 10 jours et pour aujourd’hui, les affecter aux paramètres since et until, puis les inclure dans votre demande :

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

Les paramètres since et until étant inclus, si votre plage inclut une journée qui n’est pas terminée (p. ex. aujourd’hui), les requêtes ultérieures au cours de cette journée pourront renvoyer des valeurs augmentées. Si vous n’incluez pas les paramètres since et until, l’API prendra comme valeur par défaut une plage de 2 jours : d’hier à aujourd’hui.

Exemple de requête

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

Exemple de réponse

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

Notez que comme l’exemple de requête ci-dessus n’incluait pas les paramètres since et until, l’API a renvoyé des données pour une plage par défaut de 2 jours. Chaque jour est identifié par un horodatage UTC formaté ISO 8601 avec un décalage nul qui a été affecté à une propriété end_time.

La propriété end_time indique une date limite de rétrospective de l’ensemble de données ; les données antérieures à cette valeur ne sont pas incluses dans le calcul de l’ensemble de données.

Mise à jour

Cette opération n’est pas prise en charge.

Suppression

Cette opération n’est pas prise en charge.

Nouveaux indicateurs

Syntaxe de la requête

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}

Paramètres du chemin

Paramètres de chaîne de requête

Répartition

Si vous appelez metric_type=total_value, vous pouvez également spécifier une ou plusieurs répartitions des résultats, afin de créer des sous-ensembles de moindre taille en fonction de la répartition souhaitée. Les valeurs possibles sont les suivantes :

• contact_button_type : répartit les résultats en fonction du composant de l’interface actionné par l’utilisateur ou l’utilisatrice après avoir consulté le profil de l’utilisateur·ice de l’application. Les valeurs de réponse possibles sont les suivantes :

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type : répartit les résultats par followers ou non followers. Les valeurs de réponse possibles sont les suivantes :

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type : répartit les résultats en fonction de la plateforme à partir de laquelle les spectateurs et spectatrices consultent ou interagissent avec le contenu multimédia de l’utilisateur·ice. Les valeurs de réponse possibles sont les suivantes :

  • AD
  • FEED
  • REELS
  • STORY

Consultez le tableau de la section Indicateurs pour déterminer les indicateurs qui sont compatibles avec une répartition. Si votre requête comprend un indicateur incompatible avec une répartition, l’API renvoie une erreur ("An unknown error has occurred.", « Une erreur inconnue s’est produite »). Vérifiez donc avec soin vos requêtes contenant plusieurs indicateurs.

Si vous appelez metric_type=time_series, les répartitions ne seront pas incluses dans la réponse.

Type d’indicateur

Vous pouvez choisir le mode d’agrégation de vos résultats, à savoir par période de temps ou par simple total (avec des répartitions, le cas échéant). Les valeurs possibles sont les suivantes :

• time_series : indique à l’API d’agréger les résultats par période de temps. Consultez la section Période.
• total_value : indique à l’API d’agréger les résultats en tant que simple total. Si des répartitions sont incluses dans la demande, l’ensemble de résultats sera encore subdivisé par les répartitions concernées. Consultez la section Répartition.

Période

Spécifie à l’API la période à utiliser lors de l’agrégation des résultats. Compatible uniquement avec les indicateurs associés aux interactions.

Délai

Spécifie à l’API la limite temporelle jusqu’à laquelle remonter lors de la demande d’indicateurs démographiques. Cette valeur remplace les paramètres since et until.

Plage

Affectez des horodatages UNIX aux paramètres since et until pour définir une plage. L’API inclura uniquement les données créées dans cette plage (inclusive). Si vous ne définissez pas ces paramètres, l’API cherchera jusqu’à 24 heures en arrière.

Concernant les indicateurs démographiques, le paramètre timeframe remplace ces valeurs. Consultez la section Délai.

Indicateurs

Indicateurs d’interaction

Indicateurs démographiques

Réponse

Objet JSON contenant les résultats de votre requête. En fonction des caractéristiques de votre requête, les résultats peuvent comprendre les données suivantes :

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

Contenu de la réponse

Exemple de requête d’indicateur d’interaction

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

Exemple de réponse d’indicateur d’interaction

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

Exemple de requête d’indicateur démographique

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

Exemple de réponse d’indicateur démographique

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