Récupérer des Posts historiques à l’aide de l’endpoint de recherche de l’archive complète v2

​

Introduction

Les endpoints Search Posts dans l’environnement v2 vous permettent de recevoir des Posts liés à des sujets d’intérêt, sur la base d’une query de recherche que vous définissez. Nous proposons deux endpoints distincts avec v2 Search Posts : la recherche récente, accessible à tous les développeurs disposant d’un compte approuvé et permettant de rechercher des Posts jusqu’à sept jours en arrière, et la recherche sur l’archive complète, disponible uniquement pour les chercheurs approuvés pour le parcours Academic Research, qui permet d’explorer l’intégralité de l’archive des Posts remontant à mars 2006.

Vous pouvez consulter l’ensemble de notre offre de recherche sur notre page de présentation de la recherche.

Ces endpoints Search Posts répondent à l’un des cas d’usage les plus courants pour les chercheurs universitaires, qui peuvent les utiliser pour des études longitudinales ou pour analyser un sujet ou un événement passé.

Ce tutoriel propose un guide pas à pas destiné aux chercheurs souhaitant utiliser l’endpoint de recherche sur l’archive complète afin d’explorer l’historique complet des données publiques de X. Il présentera également différentes manières de constituer un jeu de données, par exemple en récupérant des Posts géolocalisés, ainsi que la façon de parcourir les Posts disponibles pour une query.

​

Prérequis

Actuellement, cet endpoint n’est disponible que dans le cadre du parcours de produit Academic Research. Pour utiliser cet endpoint, vous devez demander l’accès. En savoir plus sur la candidature et les exigences pour ce parcours.

​

Connecter une App au Project académique

Une fois votre accès approuvé pour la filière Academic Research, vous verrez votre Project académique dans le developer portal. Depuis la section “Projects and Apps”, cliquez sur “Add App” pour connecter votre X App au Project.

Ensuite, vous pouvez soit choisir une App existante et la connecter à votre Project (comme illustré ci-dessous).

Ou vous pouvez créer une nouvelle App, lui donner un nom et cliquer sur “Complete”, pour connecter une nouvelle App à votre Project académique.

Cela vous fournira vos clés d’API et Jeton Bearer que vous pourrez ensuite utiliser pour vous connecter à l’endpoint de recherche full-archive.

Veuillez noter

Les clés dans la capture d’écran ci-dessus sont masquées, mais dans votre propre developer portal, vous pourrez voir les valeurs réelles pour l’API Key, la Clé secrète de l’API, et le Jeton Bearer. Enregistrez ces clés et le Jeton Bearer car vous en aurez besoin pour appeler l’endpoint de recherche full-archive.

​

Connexion à l’endpoint de recherche sur l’intégralité des archives

La commande cURL ci-dessous montre comment récupérer des Posts historiques depuis le compte @XDevelopers. Remplacez $BEARER_TOKEN par votre propre Jeton Bearer, collez la requête complète dans votre terminal, puis appuyez sur « Entrée ».

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

Vous verrez le JSON de la réponse.

Par défaut, seuls les 10 Posts les plus récents sont renvoyés. Si vous souhaitez plus de 10 Posts par requête, vous pouvez utiliser le paramètre max_results et le définir jusqu’à un maximum de 500 Posts par requête, comme indiqué ci-dessous :

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Créer des requêtes

Comme vous pouvez le voir dans les exemples d’appels ci‑dessus, en utilisant le paramètre query, vous pouvez spécifier les data que vous souhaitez rechercher. Par exemple, si vous souhaitez récupérer tous les Posts contenant le mot covid ou le mot coronavirus, vous pouvez utiliser l’opérateur OR entre parenthèses, et votre query peut être (covid OR coronavirus) et votre appel à l’API ressemblera alors à ce qui suit :

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

De même, si vous souhaitez obtenir tous les Posts contenant le terme covid19 qui ne sont pas des Retweets, vous pouvez utiliser l’opérateur is:retweet avec la négation logique (représentée par -), ainsi votre query peut être covid19 -is:retweet et votre appel à l’API sera :

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Consultez ce guide pour la liste complète des opérateurs pris en charge par l’endpoint de recherche de l’intégralité des archives.

​

Utiliser les paramètres start_time et end_time pour récupérer des Posts historiques

Avec l’endpoint de recherche dans l’intégralité des archives, les Posts des 30 derniers jours sont renvoyés par défaut. Si vous souhaitez récupérer des Posts âgés de plus de 30 jours, vous pouvez utiliser les paramètres start_time et end_time dans votre appel d’API. Ces paramètres doivent respecter le format date-heure RFC3339 valide, par exemple 2020-12-21T13:00:00.00Z. Ainsi, si vous souhaitez récupérer tous les Posts du compte XDevelopers pour le mois de décembre 2020, votre appel d’API sera :

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Récupération de Posts historiques géolocalisés

Les Posts géolocalisés sont des Posts auxquels sont associées des informations géographiques, telles que la ville, l’État, le pays, etc.

​

Utilisation de l’opérateur has:geo

Si vous souhaitez récupérer des Posts qui contiennent des données de géolocalisation, vous pouvez utiliser l’opérateur has:geo. Par exemple, la requête cURL suivante récupérera uniquement les Posts du compte @XDevelopers qui contiennent des données de géolocalisation :

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

Utilisation de l’opérateur place_country

De même, vous pouvez limiter les Posts contenant des données de géolocalisation à un pays spécifique à l’aide de l’opérateur place_country. La commande cURL ci-dessous récupérera tous les Posts du compte @XDevelopers en provenance des États-Unis :

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

Le pays est indiqué ci-dessus à l’aide du code alphabétique ISO à deux lettres (alpha‑2). Les codes ISO valides sont disponibles ici.

​

Récupérer plus de 500 Posts historiques à l’aide de next_token

Comme mentionné ci-dessus, par défaut vous ne pouvez obtenir que jusqu’à 500 Posts par requête pour une query vers l’endpoint de recherche sur l’intégralité des archives. S’il y a plus de 500 Posts disponibles pour votre query, votre réponse JSON inclura un next_token que vous pouvez ajouter à votre appel à l’API afin d’obtenir les Posts suivants disponibles pour cette query. Ce next_token est disponible dans l’objet meta de votre réponse JSON, qui ressemble à ceci :

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Ainsi, pour récupérer les prochains Posts disponibles, utilisez la valeur next_token de cet objet meta et passez-la comme valeur de next_token dans votre appel d’API vers l’endpoint de recherche de l’archive complète, comme indiqué ci-dessous (vous utiliserez votre propre Jeton Bearer et la valeur de Next Token obtenue lors de votre appel d’API précédent).

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

De cette façon, vous pouvez continuer à vérifier si un next_token est disponible et, si vous n’avez pas atteint le nombre de Posts que vous souhaitez collecter, vous pouvez continuer à appeler l’endpoint d’archive complète avec le nouveau next_token pour chaque requête. Gardez à l’esprit que l’endpoint de recherche d’archive complète est comptabilisé dans votre Post cap, c’est-à-dire le nombre de Posts par mois que vous pouvez obtenir via la X API par Project. Soyez donc attentif à la logique de votre code lors de la pagination des résultats afin de vous assurer de ne pas épuiser involontairement votre Post cap.

Voici quelques ressources qui peuvent vous aider lors de l’utilisation de l’endpoint de recherche d’archive complète. Nous serions ravis de recevoir vos retours. Contactez-nous sur @XDevelopers ou sur nos community forums pour toute question concernant cet endpoint.

​

Ressources supplémentaires

• Référence de l’API de l’endpoint de recherche sur l’ensemble des archives
• Apprenez les bases de la création d’une query de recherche