Enrichissement des données : Enterprise

​

Introduction

Enterprise

Les enrichissements Enterprise sont des métadonnées additionnelles incluses dans la charge utile de réponse de certaines API de données. Ils sont disponibles uniquement dans les offres d’abonnement payantes.

Le tableau ci-dessous propose une brève description de chaque enrichissement :

Enrichment:	Description:
Expanded and Enhanced URLs	Développe automatiquement les URL raccourcies (p. ex. : bitly) incluses dans le corps d’un Post et fournit les métadonnées de titre et de description HTML de la page de destination.
Matching rules object	Indique quelle(s) règle(s) ont fait correspondre les Posts reçus. L’objet renvoie le tag de règle et l’id de la règle dans l’objet de réponse.
Poll metadata	Indique la présence d’un sondage dans un Post, inclut la liste des choix du sondage, ainsi que la durée du sondage et son heure d’expiration.
Profile geo	Données de localisation de profil utilisateur dérivées, y compris les coordonnées [longitude, latitude] (lorsque possible) et les métadonnées de lieu associées.

​

URL développées et enrichies

L’enrichissement « Expanded and Enhanced URL » développe automatiquement les URL raccourcies présentes dans le corps d’un Post et ajoute l’URL obtenue comme metadata dans la charge utile. En outre, cet enrichissement fournit aussi les metadata de la page HTML à partir du title et de la description de la page de destination.

Détails importants :

• Pour résoudre un lien raccourci, notre système envoie des requêtes HTTP HEAD à l’URL fournie et suit toutes les redirections jusqu’à l’URL finale. Cette URL finale (ET NON le contenu de la page elle‑même) est ensuite incluse dans la charge utile de la réponse.

• L’enrichissement d’URL ajoute entre 5 et 10 secondes de latence aux streams en temps réel

• Pour les requêtes effectuées à la Full Archive Search API, les données d’enrichissement des URL développées ne sont disponibles que pour les Posts âgés de 13 mois ou moins.

• L’enrichissement d’URL n’est pas disponible pour les liens de Post (y compris les Tweets cités), les liens Moments et les liens de profil inclus dans un Post.   

​

Charge utile du Post

L’enrichissement d’URL développée et améliorée se trouve dans l’objet entities de la charge utile du Post — plus précisément dans l’objet entitites.urls.unwound. Il fournit les champs de metadata suivants :

• URL développée — unwound.url
• Statut HTTP de l’URL développée — unwound.status
• Titre HTML de l’URL développée — limite de 300 caractères — unwound.title
• Description HTML de l’URL développée — limite de 1000 caractères — unwound.description

Voici un exemple d’un objet entities avec l’enrichissement d’URL :

"entities": {
    "hashtags": [

    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/HkTkwFq8UT",
        "expanded_url": "http:\/\/bit.ly\/2wYTb9y",
        "display_url": "bit.ly\/2wYTb9y",
        "unwound": {
          "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/",
          "status": 200,
          "title": "11 sites web pour apprendre à coder gratuitement en 2017",
          "description": "Il est tout à fait possible d'apprendre à coder gratuitement... mais quelles sont les meilleures ressources pour y arriver ? Voici 11 sites web pour commencer."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

**Voici un exemple d’objet entities contenant un lien de Post non enrichi : **

"entities": {
  "urls": [{
    "url": "https://t.co/SywNbZdDmb",
    "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728",
    "display_url": "x.com/XDevelopers/s…",
     "indices": [
        142,
        165
     ]
   }
  ]
}

​

Opérateurs de filtrage

Les opérateurs suivants filtrent et effectuent une correspondance tokenisée sur les champs liés aux métadonnées d’URL :

url :

• Exemple : “url:tennis”
• Correspondance tokenisée sur toute URL développée contenant le mot tennis
• Peut aussi servir de filtre pour inclure ou exclure les liens d’un site web spécifique, par exemple “url:npr.org”

url_title :

• Exemple : “url_title:tennis”
• Correspondance tokenisée sur tout titre HTML d’URL développée contenant le mot tennis
• Correspond au titre HTML inclus dans la charge utile, limité à 300 caractères.

url_description :

• Exemple : “url_description:tennis”
• Correspondance tokenisée sur toute description HTML d’URL développée contenant le mot tennis
• Correspond à la description HTML incluse dans la charge utile, limitée à 1000 caractères.  

​

Codes d’état HTTP

L’enrichissement des URL développées fournit également le code d’état HTTP pour l’URL finale que nous tentons de dérouler. Dans les cas normaux, il s’agit d’une valeur 200. D’autres valeurs de la série 400 indiquent des problèmes de résolution de l’URL.

Divers codes d’état peuvent être renvoyés lors de la tentative de dérouler une URL. Pendant le déroulement d’une URL, si nous obtenons une redirection, nous la suivons indéfiniment jusqu’à ce que nous :

• Atteignions un code de la série 200 (succès)
• Atteignions un code d’une série non redirection (échec)
• Expirions parce que l’URL finale n’a pas pu être résolue dans un délai raisonnable (renvoie un 408 — délai dépassé)
• Rencontrions une exception quelconque  

Si une exception survient, nous utilisons la correspondance suivante entre les causes et les codes d’état renvoyés :

Raison	Code d’état renvoyé
Exceptions SSL	403 (Interdit)
Déroulement non autorisé par l’URL	405
Délai de socket dépassé	408 (Délai dépassé)
Exception d’hôte inconnu	404 (Introuvable)
Opération non prise en charge	404 (Introuvable)
Exception de connexion	404 (Introuvable)
Argument non valide	400 (Mauvaise requête)
Tout le reste	400 (Mauvaise requête)

​

Règles de correspondance

L’enrichissement des règles de correspondance est un objet de metadata qui indique quelle(s) règle(s) a/ont fait correspondre les Posts reçus. Cet enrichissement est le plus souvent utilisé avec le stream PowerTrack.

La correspondance s’effectue par appariement exact des termes contenus dans une règle, en analysant le contenu de l’activité avec et sans ponctuation. La correspondance n’est pas sensible à la casse. Lorsque le contenu contient tous les termes définis dans la règle, un objet matching_rules au niveau racine indique la ou les règles à l’origine de la correspondance.

PowerTrack

Les Posts délivrés via PowerTrack (temps réel, Replay et Historical) contiendront l’objet matching_rules comme suit :

"matching_rules": [{
        "tag": null,
        "id": 907728589029646336,
        "id_str": "907728589029646336"
    }]

Dans PowerTrack, l’objet matching_rules reflète toutes les règles qui ont fait correspondre le résultat. En d’autres termes, si plusieurs règles correspondent à un Post spécifique, il ne sera livré qu’une seule fois, mais l’élément matching_rules contiendra l’ensemble des règles correspondantes.

​

Métadonnées de sondage

Les métadonnées de sondage sont un enrichissement gratuit disponible dans l’ensemble des produits (APIs temps réel et historiques) dans des charges utiles au format natif enrichi. Les métadonnées indiquent la présence d’un sondage dans un Post, incluent la liste des options du sondage et précisent à la fois la durée du sondage et son heure d’expiration. Cet enrichissement facilite l’identification de la présence d’un sondage et permet le rendu correct d’un Post comportant un sondage.

Détails importants :

• Disponible sur toutes les API Enterprise (PowerTrack, Replay, Search, Historical PowerTrack)
  • Remarque : Pour Replay et Historical PowerTrack, ces metadata ont été disponibles pour la première fois le 22/02/2017.
• N’inclut pas les informations de vote ni les résultats de sondage
• Ne prend actuellement pas en charge les filtres/opérateurs
• Disponible uniquement en format natif enrichi
  • Le format natif enrichi est un paramètre contrôlé par l’utilisateur qui peut être modifié à tout moment via la Console : Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​

Charge utile de Post

Un Post de sondage contiendra les metadata suivantes dans l’objet « entities.polls » de la charge utile :

• Un tableau « options » avec jusqu’à quatre options, comprenant la position (1-4) et le libellé de l’option
• Date d’expiration du sondage
• Durée du sondage

Voir l’exemple de charge utile ci-dessous pour référence.

​

Exemple de charge utile

Ci-dessous, un extrait de la charge utile au format natif enrichi mettant en évidence les metadata de sondage ajoutées :

"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"La meilleure réponse"
                   },
                   {
                      "position":2,
                      "text":"La meilleure réponse"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

​

Géo du profil

​

Introduction

De nombreux profils d’utilisateurs X incluent des informations de localisation publiques fournies par l’utilisateur. Ces données sont renvoyées sous forme de chaîne de caractères dans user.location (voir User object data dictionary). Le Profile Geo Enrichment ajoute des géodonnées structurées pertinentes pour la valeur de user.location en géocodant et en normalisant les chaînes de localisation lorsque cela est possible. Les coordonnées latitude/longitude et les métadonnées de lieux associées sont ajoutées à user.derived.locations uniquement lorsqu’elles sont incluses dans la charge utile du Post dans les produits d’API Enterprise. Ces données sont disponibles lors de l’utilisation du format natif enrichi et peuvent être filtrées à l’aide d’une combinaison de règles PowerTrack.

Remarque : Certaines des géodonnées utilisées pour créer l’enrichissement Profile Geo proviennent de GeoNames.org et sont utilisées par X sous la licence Creative Commons Attribution 3.0.

Les données Profile Geo seront incluses dans les API PowerTrack, Replay, Volume Stream, Search et Historical PowerTrack de X.

​

Données de géolocalisation du profil

Nom du champ natif enrichi	Exemple de valeur	Description
user.derived.locations.country	United States	Le pays d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.country_code	US	Un code pays ISO-3166 à deux lettres correspondant au pays d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.locality	Birmingham	La localité (généralement la ville) d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.region	Alabama	La région (généralement l’État/la province) d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.sub_region	Jefferson County	La sous-région (généralement le comté) d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.full_name	Birmingham, Alabama, United States	Le nom complet (hors sous-région) du lieu d’origine de l’utilisateur qui a créé le Post.
user.derived.locations.geo	Voir ci-dessous	Un tableau qui contient une valeur lat/long pour une coordonnée correspondant au niveau de granularité le plus fin du lieu d’origine de l’utilisateur qui a créé le Post.

Les API Historical PowerTrack, Search et PowerTrack prennent en charge le filtrage basé sur les données de géolocalisation du profil. Consultez la documentation produit appropriée pour plus de détails sur les opérateurs disponibles pour filtrer les données de géolocalisation du profil.

​

Exemple de payload

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "États-Unis",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Jefferson County",
                    "full_name": "Birmingham, Alabama, États-Unis",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

​

Limitations

• L’enrichissement Profile Geo cherche à déterminer le meilleur correspondant pour le lieu géographique indiqué dans la chaîne de localisation du profil. Le résultat peut ne pas être exact dans tous les cas, en raison de facteurs tels que l’existence de plusieurs lieux aux noms similaires ou de noms ambigus.
• Si aucune valeur n’est fournie dans le champ de localisation du profil de l’utilisateur (actor.location), nous n’essaierons pas d’établir de classification.
• Niveau de précision : si un enrichissement Profile Geo ne peut être déterminé avec confiance qu’au niveau du pays ou de la région, les géographies de niveau inférieur comme subRegion et locality seront omises du payload.
• L’enrichissement Profile Geo fournit des coordonnées lat/long (un point unique) correspondant au niveau de précision des résultats de l’enrichissement. Ces coordonnées représentent le centre géographique du lieu déterminé. Par exemple, si le niveau de précision est « pays », alors ces coordonnées sont définies sur le centre géographique de ce pays.
• Les opérateurs PowerTrack fournis pour les propriétés d’adresse (locality/region/country/country code) sont volontairement granuleux afin de permettre de nombreuses combinaisons de règles. Lorsque vous ciblez un lieu spécifique partageant son nom avec un autre, envisagez de combiner des règles d’adresse. Par exemple, ce qui suit évitera les correspondances pour “San Francisco, Philippines” : profile_locality:“San Francisco” profile_region:California. Lors de la création de règles qui ciblent des champs Profile Geo individuels, gardez à l’esprit que chaque niveau supplémentaire de granularité réduira le volume de résultats. Dans certains cas, lorsque vous cherchez à analyser des données d’une ville, vous pouvez choisir de vous appuyer uniquement sur une règle de région si celle-ci recouvre largement la ville; par exemple, la ville de Zurich, en Suisse, peut être ciblée efficacement, ainsi que ses environs, avec profile_region:“Zurich”.
• Utilisation avec les Posts « Native Geo » : l’enrichissement Profile Geo fournit un type alternatif de géographie pour un Post, différent de la valeur geo native dans le payload. Ces deux types de géographie peuvent être combinés pour capturer tous les Posts pertinents liés à une zone donnée (selon les géodonnées disponibles), bien qu’ils ne soient pas conceptuellement équivalents.