Créer une requête

Découvrez comment créer des requêtes de recherche à l’aide d’opérateurs

Les points de terminaison de recherche acceptent une requête unique via une requête GET et renvoient un ensemble de Publications historiques correspondant à cette requête. Les requêtes sont constituées d’opérateurs qui ciblent différents attributs de Publication.

---

​

Limites des requêtes

Vos requêtes seront limitées en fonction du niveau d’accès que vous utilisez :

Niveau d’accès	Recherche récente	Recherche dans l’intégralité des archives
En libre-service	512 caractères	1 024 caractères
Enterprise	4 096 caractères	4 096 caractères

---

​

Disponibilité des opérateurs

Bien que la plupart des opérateurs soient disponibles pour l’ensemble des développeurs, certains sont réservés à certains niveaux d’accès :

• Opérateurs de base : Disponibles avec n’importe quel Project
• Opérateurs avancés : Disponibles avec un Project disposant de certains niveaux d’accès

Consultez la liste complète des opérateurs pour plus de détails sur leur disponibilité.

---

​

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, cette requête fonctionne parce que #hashtag est un opérateur autonome :

#xapiv2

Les opérateurs nécessitant une conjonction ne peuvent pas être utilisés seuls dans une requête ; ils ne peuvent l’être que si au moins un opérateur autonome est inclus. En effet, n’utiliser que ces opérateurs ferait correspondre un volume extrêmement élevé de Publications.

Par exemple, les requêtes suivantes ne sont pas prises en charge car elles ne comportent que des opérateurs nécessitant une conjonction :

has:media

has:links OR is:retweet

Si nous ajoutons un opérateur isolé, comme l’expression "X data", la requête fonctionne correctement :

"X data" has:mentions (has:media OR has:links)

---

​

Opérateurs booléens et regroupement

Enchaînez plusieurs opérateurs à l’aide des outils suivants :

Opérateur	Description	Exemple
AND (espace)	Les Publications doivent satisfaire les deux conditions	snow day #NoSchool correspond aux Publications contenant “snow” ET “day” ET #NoSchool
OR	Les Publications doivent satisfaire l’une ou l’autre des conditions	grumpy OR cat OR #meme correspond aux Publications contenant “grumpy” OU “cat” OU #meme
NOT (tiret)	Exclure les Publications correspondant à cette condition	cat #meme -grumpy correspond aux Publications contenant “cat” et #meme mais PAS “grumpy”
Regroupement (parenthèses)	Regrouper des opérateurs	(grumpy cat) OR (#meme has:images) correspond à l’un ou l’autre des groupes

Remarque sur les négations

• L’opérateur -is:nullcast doit toujours être utilisé sous forme négative
• Les opérateurs négatifs ne peuvent pas être utilisés seuls
• Ne regroupez pas les opérateurs négatifs. Au lieu de skiing -(snow OR day OR noschool), utilisez skiing -snow -day -noschool

---

​

Ordre des opérations

Lorsque vous combinez AND et OR :

1. Les opérateurs reliés par l’opérateur logique AND sont d’abord combinés
2. Ensuite, les opérateurs reliés par l’opérateur logique OR sont appliqués

Exemples :

Requête	Interprétée comme
apple OR iphone ipad	apple OR (iphone ipad)
ipad iphone OR android	(iphone ipad) OR android

Pour éliminer toute ambiguïté, utilisez des parenthèses :

(apple OR iphone) ipad

iphone (ipad OR android)

---

​

Ponctuation, signes diacritiques et sensibilité à la casse

Signes diacritiques : Les requêtes de recherche avec accents ou signes diacritiques renvoient des Publications avec et sans accents. Par exemple, Diacrítica correspond à la fois à Diacrítica et Diacritica.

Sensibilité à la casse : Tous les opérateurs sont insensibles à la casse. La requête cat correspond à cat, CAT et Cat.

Le flux filtré se comporte différemment

Lors de la création de règles de flux filtré, les mots-clés avec accents ne correspondent qu’aux Publications qui incluent également l’accent. Par exemple, Diacrítica correspond uniquement à Diacrítica, et pas à Diacritica.

---

​

Correspondance pour les Quote Tweets

Lors de l’utilisation de Search Posts, les opérateurs effectuent la correspondance sur le contenu du Quote Tweet, mais pas sur le contenu de la Publication d’origine citée.

Filtered stream se comporte différemment — il effectue la correspondance à la fois sur le Quote Tweet et sur le contenu de la Publication originale.

---

​

Spécificité et efficacité

L’utilisation d’opérateurs génériques, comme un simple mot-clé ou un hashtag, n’est pas recommandée — cela renverra un volume massif de Publications et épuisera rapidement votre quota d’utilisation.

Conseils pour formuler des requêtes efficaces :

1. Commencez de manière spécifique, puis élargissez — Créez des requêtes ciblées qui renvoient des résultats pertinents
2. Utilisez plusieurs opérateurs — Combinez les opérateurs pour restreindre les résultats
3. Surveillez le nombre de caractères — Toute la chaîne de requête est comptabilisée dans la limite

Exemple de progression :

# Too broad - 200,000+ Posts per day
happy

# Mieux - ajoute un filtre de langue et des exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet

---

​

Construire progressivement une requête

​

Étape 1 : Commencez par une requête simple

happy OR happiness

​

Étape 2 : Tester et affiner en fonction des résultats

Nous avons trouvé des Publications dans de nombreuses langues. Appliquez un filtre de langue :

(happy OR happiness) lang:en

Nous recevons des vœux d’anniversaire. Excluez-les ainsi que les Retweets :

(happy OR happiness) lang:en -birthday -is:retweet

​

Étape 3 : Élargir pour améliorer la couverture

Nous voulons capter davantage de signaux de sentiment. Ajoutez des mots-clés connexes :

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

​

Étape 4 : Ajuster en fonction des tendances

Des Publications liées aux fêtes apparaissent. Excluez-les :

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

---

​

Ajouter une requête à votre appel

Utilisez le paramètre query et appliquez un encodage HTTP à votre requête :

curl "https://api.x.com/2/tweets/search/recent?\
query=cat%20has%3Amedia%20-grumpy&\
tweet.fields=created_at&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

​

Exemples de requêtes

​

Suivi d’une catastrophe naturelle

Faire correspondre des Publications provenant d’agences météorologiques concernant l’ouragan Harvey :

Requête :

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

URL complète de la requête :

https://api.x.com/2/tweets/search/recent?query=has%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)%20-is%3Aretweet

​

Analyse des sentiments pour #nowplaying

Sentiment positif :

#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

Sentiment négatif :

#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

​

Utiliser les annotations de Publication

Recherchez des Publications en japonais sur les animaux de compagnie (sauf les chats) avec des images en utilisant l’opérateur context: :

Commencez par utiliser Recherche de Publications avec tweet.fields=context_annotations pour identifier les ID domain.entity :

• Chats : domain 66, entity 852262932607926273
• Animaux de compagnie : domain 65, entity 852262932607926273

Requête :

context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja

---

​

Outils

Générateur de requêtes

Créez et testez vos requêtes de manière interactive

---

​

Prochaines étapes

Référence des opérateurs

Liste complète des opérateurs disponibles

Démarrage rapide de la recherche

Effectuez votre première requête de recherche

Guide d'intégration

Documentation complète d’intégration