Skip to main content

​
Créer une requête

Limitations des requêtes ! Vos requêtes seront limitées en fonction du niveau d’accès que vous utilisez.  Votre requête peut contenir 512 caractères pour les clients facturés à l’usage, ou jusqu’à 4 096 caractères pour les clients Enterprise. Si vous avez un accès Enterprise, veuillez contacter votre chargé de compte.  Disponibilité des opérateurs La plupart des opérateurs sont disponibles pour tout développeur, mais certains sont réservés aux personnes ayant obtenu une validation pour un accès Enterprise. Nous indiquons dans le tableau des opérateurs le niveau d’accès requis pour chaque opérateur à l’aide des libellés suivants :
  • Opérateurs de base : Disponibles avec n’importe quel Project.
  • Opérateurs avancés : Disponibles avec un Project disposant d’un accès Enterprise.   

​
Types d’opérateurs : autonomes et nécessitant une conjonction

Les opérateurs autonomes peuvent être utilisés seuls ou avec n’importe quel autre opérateur (y compris ceux qui nécessitent une conjonction). Par exemple, la requête suivante fonctionnera parce qu’elle utilise l’opérateur #hashtag, qui est autonome : #xapiv2 Les opérateurs nécessitant une conjonction ne peuvent pas être utilisés seuls dans une requête ; ils ne peuvent être utilisés que lorsqu’au moins un opérateur autonome est inclus dans la requête. En effet, utiliser ces opérateurs seuls serait beaucoup trop général et renverrait un volume extrêmement élevé de Publications. Par exemple, les requêtes suivantes ne sont pas prises en charge puisqu’elles ne contiennent que des opérateurs nécessitant une conjonction : has:media has:links OR is:retweet Si nous ajoutons un opérateur autonome, comme l’expression « X data », la requête fonctionnera alors correctement. « X data » has:mentions (has:media OR has:links)

​
Opérateurs booléens et regroupement

Si vous souhaitez enchaîner plusieurs opérateurs dans une seule requête, vous disposez des outils suivants : Remarque sur les négations Les opérateurs -is:nullcast doivent toujours être niés. Les opérateurs niés ne peuvent pas être utilisés seuls. Ne niez pas un ensemble d’opérateurs regroupés entre parenthèses. À la place, niez chaque opérateur individuellement. Par exemple, au lieu d’utiliser skiing -(snow OR day OR noschool), nous vous conseillons d’utiliser skiing -snow -day -noschool.  Ordre d’évaluation Lorsque vous combinez la logique AND et OR, l’ordre d’évaluation suivant détermine la façon dont votre requête est interprétée.
  1. Les opérateurs reliés par une logique AND sont combinés en premier
  2. Ensuite, les opérateurs reliés par une logique OR sont appliqués
Par exemple :
  • apple OR iphone ipad sera évalué comme apple OR (iphone ipad)
  • ipad iphone OR android sera évalué comme (iphone ipad) OR android
Pour éliminer toute incertitude et vous assurer que votre requête est évaluée comme prévu, regroupez les termes avec des parenthèses lorsque cela est approprié.  Par exemple :
  • (apple OR iphone) ipad
  • iphone (ipad OR android)  
Ponctuation, diacritiques et sensibilité à la casse Si vous indiquez un mot-clé ou un hashtag dans une requête avec des accents ou des diacritiques, il correspondra au texte de la Publication qui contient à la fois le terme avec accents et diacritiques, ainsi que ce même terme avec des caractères non accentués. Par exemple, des requêtes avec le mot-clé Diacrítica ou le hashtag #cumpleaños correspondront à Diacrítica ou #cumpleaños, ainsi qu’à Diacritica ou #cumpleanos sans tilde sur í ou eñe. Les caractères avec accents ou diacritiques sont traités de la même manière que les caractères normaux et ne sont pas traités comme des limites de mots. Par exemple, une requête avec le mot-clé cumpleaños ne correspondrait qu’aux activités contenant le mot cumpleaños et ne correspondrait pas aux activités contenant cumplea, cumplean ou os. Tous les opérateurs sont évalués de manière insensible à la casse. Par exemple, la requête cat correspondra aux Publications contenant toutes les variantes suivantes : cat, CAT, Cat. Le comportement de correspondance du flux filtré diffère de celui des décomptes de Publications. Lors de la création d’une règle de flux filtré, sachez que les mots-clés et hashtags incluant des accents et des diacritiques ne correspondront qu’aux termes qui incluent également l’accent et le diacritique, et ne correspondront pas aux termes utilisant à la place des caractères normaux.  Par exemple, des règles de flux filtré qui incluent le mot-clé Diacrítica ou le hashtag #cumpleaños ne correspondront qu’aux termes Diacrítica et #cumpleaños, et ne correspondront pas à Diacritica ou #cumpleanos sans tilde sur í ou eñe. Spécificité et efficacité Lorsque vous commencez à élaborer votre requête, il est important de garder quelques éléments à l’esprit.
  • L’utilisation d’opérateurs génériques et isolés pour votre requête, comme un simple mot‑clé ou un #hashtag, n’est généralement pas recommandée, car cela correspondra probablement à un volume massif de Publications. Créer une requête plus robuste produira un ensemble plus spécifique de Publications correspondantes et, idéalement, augmentera la précision de vos décomptes de Publications afin de vous aider à dégager des insights plus pertinents. 
    • Par exemple, si votre requête est simplement le mot‑clé happy, vous obtiendrez probablement entre 200 000 et 300 000 Publications par jour.
    • L’ajout d’opérateurs conditionnels supplémentaires restreint vos résultats, par exemple (happy OR happiness) place_country:GB -birthday -is:retweet
  • Rédiger des requêtes efficaces est également utile pour respecter la limite de longueur de la requête en nombre de caractères. Le nombre de caractères inclut l’intégralité de la chaîne de requête, y compris les espaces et les opérateurs.
    • Par exemple, la requête suivante comporte 59 caractères : (happy OR happiness) place_country:GB -birthday -is:retweet
Comportement de correspondance des Quote Tweets Lorsque vous utilisez les endpoints de décompte de Publications, les opérateurs ne font pas correspondre le contenu de la Publication originale qui a été citée, mais correspondent au contenu inclus dans le Quote Tweet. Cependant, veuillez noter que le flux filtré fera correspondre à la fois le contenu de la Publication originale citée et le contenu du Quote Tweet.   Construction itérative d’une requête Testez votre requête tôt et souvent Obtenir dès la première fois une requête qui renvoie les « bons » résultats est rare. Il y a tellement de contenu sur X qui peut ou non être évident au premier abord, et la syntaxe de requête décrite ci‑dessus peut être difficile à aligner sur la requête souhaitée. Lorsque vous construisez une requête, il est important de la tester périodiquement à l’aide de l’un des endpoints Search Post pour vérifier que les Publications qui correspondent à votre requête sont pertinentes pour votre cas d’usage. Pour cette section, nous allons partir de la requête suivante et l’ajuster en fonction des résultats que nous obtenons pendant nos tests :  happy OR happiness Utiliser les résultats pour restreindre la requête Lorsque vous testez la requête avec Search Posts, vous devez parcourir les Publications renvoyées pour vérifier qu’elles incluent les données que vous vous attendez à recevoir. Commencer par une requête large et un surensemble de Publications correspondantes vous permet d’examiner le résultat et de restreindre la requête afin de filtrer les résultats non souhaités.   Lorsque nous avons testé la requête d’exemple, nous avons remarqué que nous recevions des Publications dans un grand nombre de langues différentes. Dans cette situation, nous voulons uniquement recevoir des Publications en anglais, nous allons donc ajouter l’opérateur lang: : (happy OR happiness) lang:en Le test a renvoyé un certain nombre de Publications souhaitant un joyeux anniversaire, nous allons donc ajouter -birthday en tant qu’opérateur de mot‑clé négatif. Nous voulons également ne recevoir que des Publications originales, nous avons donc ajouté l’opérateur négatif -is:retweet : (happy OR happiness) lang:en -birthday -is:retweet Ajuster pour inclure davantage lorsque nécessaire Si vous constatez que vous ne recevez pas via Search Posts des données que vous attendiez, alors que vous savez qu’il existe des Publications qui devraient être renvoyées, vous devrez peut‑être élargir votre requête en supprimant des opérateurs qui filtrent les données souhaitées.  Dans notre exemple, nous avons remarqué qu’il y avait d’autres Publications dans notre timeline personnelle qui exprimaient l’émotion recherchée mais n’étaient pas incluses dans les résultats de test. Pour garantir une meilleure couverture, nous allons ajouter les mots‑clés excited et elated. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet Ajuster pour les tendances populaires/pics sur la période Les tendances apparaissent et disparaissent rapidement sur X. Le maintien de votre requête doit être un processus actif. Si vous prévoyez d’utiliser une requête pendant un certain temps, nous vous conseillons de vérifier périodiquement les données que vous recevez afin de déterminer si des ajustements sont nécessaires. Dans notre exemple, nous remarquons que nous avons commencé à recevoir des Publications souhaitant de « joyeuses fêtes ». Comme nous ne voulons pas que ces Publications soient incluses dans nos résultats, nous allons ajouter le mot‑clé négatif -holidays. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays  Une fois que vous avez correctement testé et itéré votre requête, vous pouvez commencer à l’envoyer avec les endpoints de décompte de Publications afin de ne recevoir que le volume de Publications plutôt que l’intégralité des payloads de Publication.

​
Ajout d’une requête de recherche à votre appel

Pour ajouter votre requête de recherche à votre appel, vous devez utiliser le paramètre query. Comme pour tout paramètre de requête, vous devez vous assurer d’encoder en HTTP la requête de recherche que vous avez définie. Voici un exemple de ce à quoi cela peut ressembler avec une commande cURL. Si vous souhaitez utiliser cette commande, veillez à remplacer $BEARER_TOKEN par votre propre Jeton Bearer :

​
Exemples de requêtes

Suivi d’une catastrophe naturelle La requête suivante permettait de faire correspondre des Publications originales provenant d’agences météorologiques et de stations de mesure qui parlent de l’ouragan Harvey, qui a frappé Houston en 2017. Voici à quoi ressemblerait la requête sans l’encodage HTTP : has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet Et voici à quoi ressemblerait la requête avec l’encodage HTTP, le paramètre de requête et l’URI des décomptes récents de Publications : https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1) Analyse du sentiment d’une conversation La règle suivante peut être utilisée pour mieux comprendre le sentiment de la conversation qui se développe autour du hashtag #nowplaying, mais limitée aux Publications publiées en Amérique du Nord. Voici à quoi ressembleraient les deux requêtes différentes, l’une pour le positif et l’autre pour le négatif, sans l’encodage HTTP : #nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing #nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible Et voici à quoi ressemblerait la requête avec l’encodage HTTP, le paramètre de requête et l’URI des décomptes récents de Publications : https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place_country%3AUS%20OR%20place_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing https://api.x.com/2/tweets/counts/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place_country%3AUS%20OR%20place_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible Trouver des Publications liées à une annotation de Publication spécifique Cette règle a été conçue pour filtrer les Publications originales qui incluent l’image d’un animal de compagnie qui n’est pas un chat, lorsque la langue identifiée dans la Publication est le japonais. Pour ce faire, nous avons utilisé l’opérateur context: pour tirer parti de la fonctionnalité Post annotation. Nous avons d’abord utilisé l’endpoint Post lookup et le paramètre de champs tweet.fields=context_annotations pour identifier les IDs domain.entity dont nous avons besoin dans notre requête :
  • Les Publications liées aux chats renvoient le domain 66 (catégorie Interests and Hobbies) avec l’entity 852262932607926273 (Cats). 
  • Les Publications liées aux animaux de compagnie renvoient le domain 65 (Interests and Hobbies Vertical) avec l’entity 852262932607926273 (Pets). 
Voici à quoi ressemblerait la requête sans l’encodage HTTP : context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja Et voici à quoi ressemblerait la requête avec l’encodage HTTP, le paramètre de requête et l’URI des décomptes récents de Publications : https://api.x.com/2/tweets/counts/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja

​
Opérateurs