v1 vers v2

Version standard v1.1 comparée à X API v2

Si vous avez travaillé avec la v1.1 search/posts, l’objectif de ce guide est de vous aider à comprendre les similitudes et les différences entre la recherche standard et l’endpoint de recherche de Publications de X API v2.

• Similarités
  • Contexte utilisateur OAuth 1.0a et OAuth 2.0 App-only
  • Prise en charge de l’historique de modification des Publications et de leurs métadonnées. 
• Différences

  • URL des endpoints

  • Exigences pour les Apps et les Projets

  • Format des données de la réponse

  • Paramètres de la requête

  • Nouveaux opérateurs de requête

  • Priorité des opérateurs AND / OR 

Similarités

Authentification OAuth 1.0a User Context et OAuth 2.0 App-Only

L’endpoint search/posts de la v1.1 et l’endpoint recent search de X API v2 prennent en charge à la fois OAuth 1.0a User Context et OAuth 2.0 App-Only. 

Par conséquent, si vous utilisiez précédemment l’endpoint de recherche standard v1.1, vous pouvez continuer à utiliser la même méthode d’authentification en migrant vers la version X API v2. 

En fonction de la bibliothèque ou du package d’authentification que vous choisissez, l’authentification App-Only est probablement le moyen le plus simple pour commencer et peut être configurée au moyen d’un simple en-tête de requête. Pour savoir comment générer un App Access Token, consultez ce guide OAuth 2.0 App-Only. 

Si vous souhaitez profiter de la possibilité de récupérer des métriques privées ou publicitaires avec l’endpoint de X API v2, vous devrez utiliser OAuth 1.0a User Context et transmettre les jetons d’accès de l’utilisateur qui a publié la Publication dont vous souhaitez récupérer les métriques. 

Prise en charge de l’historique de modification des Publications et des métadonnées

Les deux versions fournissent des métadonnées décrivant tout historique de modification. Consultez les Références de l’API de recherche et la page de notions fondamentales sur la modification des Publications pour plus de détails. 

Différences

URLs d’endpoint

• Endpoints standard v1.1 :

  • https://api.x.com/1.1/search/tweets

• Endpoint X API v2 :

  • https://api.x.com/2/tweets/search/recent  

Exigences relatives aux Apps et aux Projects

Les endpoints X API v2 exigent que vous utilisiez des identifiants provenant d’une developer App associée à un Project lorsque vous authentifiez vos requêtes. Tous les endpoints X API v1.1 peuvent utiliser des identifiants provenant d’Apps autonomes ou d’Apps associées à un Project. 

Format des données de réponse

L’une des plus grandes différences entre les versions d’endpoint standard v1.1 et X API v2 est la façon dont vous sélectionnez les champs qui sont renvoyés dans votre payload.

Pour les endpoints standard, vous recevez de nombreux champs de réponse par défaut, puis vous avez la possibilité d’utiliser des paramètres pour identifier quels champs ou ensembles de champs doivent être renvoyés dans le payload.

La version X API v2 ne fournit par défaut que le champ id de la Publication et le champ text. Pour demander des champs ou objets supplémentaires, vous devrez utiliser les paramètres fields et expansions. Tous les champs de Publication que vous demandez à partir de ces endpoints seront renvoyés dans l’objet Publication principal. Tout objet utilisateur, média, sondage ou lieu étendu, ainsi que leurs champs, sera renvoyé dans un objet includes au sein de votre réponse. Vous pouvez ensuite faire correspondre les objets étendus à l’objet Publication en faisant correspondre les id présents à la fois dans la Publication et dans l’objet étendu. 

Nous vous encourageons à en savoir plus sur ces nouveaux paramètres dans leurs guides respectifs, ou en lisant notre guide sur comment utiliser les paramètres fields et expansions. 

Nous avons également préparé un guide de migration de format de données qui peut vous aider à faire la correspondance entre les champs standard v1.1 et les nouveaux champs v2. Ce guide vous fournit aussi le paramètre spécifique d’expansion et de champ que vous devrez transmettre avec votre requête v2 pour renvoyer des champs spécifiques.   

En plus des modifications de la façon dont vous demandez certains champs, X API v2 introduit également de nouveaux modèles JSON pour les objets renvoyés par les API, notamment les objets Post et user.

• Au niveau racine JSON, les endpoints standard renvoient les objets Publication dans un tableau statuses, tandis que X API v2 renvoie un tableau data. 
• Au lieu de faire référence à des « statuses » Retweeted et Quoted, le JSON X API v2 fait référence à des Tweets Retweeted et Quoted. De nombreux champs hérités et obsolètes, tels que contributors et user.translator_type, sont supprimés. 
• Au lieu d’utiliser à la fois favorites (dans l’objet Publication) et favourites (dans l’objet user), X API v2 utilise le terme like. 
• X adopte la convention selon laquelle les valeurs JSON dépourvues de valeur (par exemple null) ne sont pas écrites dans le payload. Les attributs de Publication et d’utilisateur ne sont inclus que s’ils ont des valeurs non nulles.   

Nous avons également introduit un nouvel ensemble de champs dans l’objet Post, notamment les suivants :

• Un champ conversation_id
• Deux nouveaux champs annotations, notamment context et entities
• Plusieurs nouveaux champs metrics 
• Un nouveau champ reply_setting, qui indique qui peut répondre à une Publication donnée

Paramètres de requête

Les paramètres de requête standard v1.1 suivants ont des équivalents dans X API v2 :

Recherche standard v1.1	Recherche de Publications v2
q	query
	start_time (YYYY-MM-DDTHH:mm:ssZ)
until (YYYY-MM-DD)	end_time (YYYY-MM-DDTHH:mm:ssZ)
since_id	since_id
max_id	until_id
count	max_results
La réponse fournit search_metadata.next_results	next_token

Il existe également un ensemble de paramètres de requête standard de recherche de Publications non pris en charge dans X API v2 :

Paramètre standard v1.1	Détails
geocode	La recherche de Publications prend en charge les opérateurs géographiques pour les requêtes basées sur la localisation.
locale	Avec la recherche standard, cela servait à spécifier la langue de la requête, mais n’a jamais été pleinement implémenté.
lang	Les endpoints de recherche de Publications fournissent un opérateur de requête lang pour rechercher selon les langues d’intérêt.
include_entities	Les entités de la Publication sont toujours incluses.
result_type	Les endpoints de recherche de Publications renvoient toutes les Publications correspondantes, quel que soit le niveau d’engagement.
extended	X API v2 est conçue dès le départ pour prendre en charge les Publications jusqu’à 280 caractères. Avec v2, il n’existe pas de notion de Publications « étendues ».

Voici un exemple de requête qui montre la différence entre une requête standard et une requête de recherche de Publications :

Standard v1.1	X API v2
https://api.x.com/1.1/search/tweets.json?q=snow&count=50	https://api.x.com/2/tweets/search/recent?query=snow&max_results=50

Ces requêtes renverront toutes deux les 50 Publications les plus récentes qui contiennent le mot‑clé snow. La requête v2 renverra les champs id et text par défaut des Publications correspondantes. Voici un exemple de spécification de champs supplémentaires de Publications et d’utilisateur à inclure dans le payload JSON :

X API v2
https://api.x.com/2/tweets/search/recent?query=snow&max_results=50&tweet.fields=id,created_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description

Nouveaux opérateurs de requête

La recherche de Publications introduit de nouveaux opérateurs pour prendre en charge deux nouvelles fonctionnalités de X API v2 : 

• Conversation IDs - À mesure que les conversations se déroulent sur X, un ID de conversation sera disponible pour marquer les Publications qui font partie de la conversation. Toutes les Publications de la conversation auront leur champ conversation_id défini sur l’id de la Publication qui l’a initiée. 
  • conversation_id:
• X Annotations fournissent des informations contextuelles sur les Publications et incluent des annotations d’entité et de contexte. Les entités sont constituées de personnes, de lieux, de produits et d’organisations. Les contextes sont des domaines, ou des thèmes, dont font partie les entités mises en avant. Par exemple, les personnes mentionnées dans une Publication peuvent avoir un contexte qui indique si elles sont des athlètes, des acteurs ou des responsables politiques.  

  • context : correspond aux Publications qui ont été annotées avec un contexte d’intérêt. 

  • entity : correspond aux Publications qui ont été annotées avec une entité d’intérêt. 

     

Priorité des opérateurs AND / OR

L’élément de base pour construire des requêtes de recherche est l’utilisation des groupements logiques OR et AND. L’API standard de recherche applique les OR avant les AND, tandis que les endpoints Search Posts (ainsi que les versions premium et enterprise) appliquent les AND avant les OR. Cette différence est cruciale lors de la traduction de requêtes entre les deux. 

Par exemple, avec la recherche standard, si vous souhaitez faire correspondre des Publications contenant le mot-clé « storm » qui mentionnent le mot « colorado » ou le hashtag #COwx, vous pouvez le faire avec la requête suivante :

storm #COwx OR colorado

Avec la priorité des opérateurs de Search Posts, les AND sont appliqués avant les OR. Ainsi, la requête ci-dessus est équivalente à : 

(storm #COwx) OR colorado

Cependant, la règle ci-dessus ferait correspondre n’importe quelle Publication qui mentionne « Colorado », que la Publication mentionne ou non « storm » ou le hashtag #COwx. En outre, elle ferait également correspondre les Publications qui mentionnent à la fois le mot-clé « storm » et le hashtag #COwx. 

Pour que la requête se comporte comme prévu à l’origine, les clauses OR doivent être regroupées. La traduction de la requête standard d’origine vers Search Posts serait :

storm (#COwx OR colorado)

Ces deux règles produisent des résultats très différents. Pour le mois d’octobre 2019, la règle d’origine fait correspondre plus de 1 175 000 Publications, tandis que la règle correctement traduite fait correspondre environ 5 600 Publications. Veillez à bien gérer vos AND et OR, et utilisez des parenthèses lorsque c’est nécessaire. 

Requêtes cURL

La section suivante présente des requêtes cURL pour le endpoint standard v1.1 et son endpoint équivalent en v2.

Les requêtes sont effectuées à l’aide de [OAuth 2.0 App-Only](https://developer.x.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). Pour exécuter les requêtes cURL suivantes, vous devez remplacer ACCESS_TOKEN dans l’en-tête d’autorisation par le jeton d’accès de votre App. Pour les endpoints v2, le jeton d’accès de votre App doit appartenir à une developer App au sein d’un Project. 

La charge utile de la réponse renvoyée par le endpoint v1.1 sera différente de la charge utile de la réponse renvoyée par le endpoint v2. Avec v2, la réponse inclura les champs par défaut, ainsi que tout autre champ demandé avec les paramètres fields et expansions. Vous pouvez utiliser ces paramètres pour demander un ensemble différent de champs à renvoyer.

Standard v1.1 GET search/tweets → v2 GET tweets/search/recent

cURL (v1.1)

shellscript

curl --request GET \
  --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

Étapes suivantes

Consultez notre guide de démarrage rapide pour la recherche récente avec X API v2

Consultez la Référence de l’API pour la recherche récente

Découvrez quelques exemples de code pour ces endpoints

Guide pas à pas pour effectuer votre première requête de recherche récente