Guide d'intégration

Concepts clés et bonnes pratiques pour intégrer la recherche de Publications

Ce guide présente les concepts clés nécessaires pour intégrer les endpoints de recherche de publications à votre application.

---

​

Authentification

Tous les points de terminaison de la X API v2 nécessitent une authentification. Choisissez la méthode qui correspond à votre cas d’utilisation :

Méthode	Idéal pour	Peut accéder aux métriques privées ?
OAuth 2.0 App-Only	Serveur à serveur, données publiques	Non
OAuth 2.0 Authorization Code with PKCE	Applications destinées aux utilisateurs	Oui (pour les Publications de l’utilisateur autorisé)
OAuth 1.0a User Context	Anciennes intégrations	Oui (pour les Publications de l’utilisateur autorisé)

​

Authentification App-only

Pour les données publiques de Publications, utilisez un jeton Bearer :

cURL

shellscript

curl "https://api.x.com/2/tweets/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Authentification en contexte utilisateur

Pour accéder aux métriques privées, authentifiez-vous au nom de l’auteur de la Publication :

Les champs suivants nécessitent une authentification en contexte utilisateur :

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics
• media.fields.non_public_metrics
• media.fields.promoted_metrics
• media.fields.organic_metrics

---

​

Champs et expansions

X API v2 retourne par défaut un volume minimal de données. Utilisez les paramètres fields et expansions pour demander précisément les données dont vous avez besoin.

​

Réponse par défaut

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!",
    "edit_history_tweet_ids": ["1234567890"]
  }
}

​

Champs disponibles

tweet.fields

Champ	Description
created_at	Horodatage de création de la Publication
author_id	ID utilisateur de l’auteur
public_metrics	Nombre de J’aime, retweets, réponses, citations
entities	Hashtags, mentions, URLs, cashtags
attachments	Clés de média, ID de sondage
conversation_id	Identifiant de fil
context_annotations	Catégories de sujets/entités
in_reply_to_user_id	Utilisateur auquel on répond
lang	Langue détectée
source	Client utilisé pour publier
possibly_sensitive	Indicateur de contenu sensible
reply_settings	Qui peut répondre

user.fields (requiert l’expansion author_id)

Champ	Description
username	@handle
name	Nom affiché
profile_image_url	URL de l’avatar
verified	Statut de vérification
description	Biographie
public_metrics	Nombre d’abonnés/abonnements
created_at	Date de création du compte

media.fields (requiert l’expansion attachments.media_keys)

Champ	Description
url	URL du média
preview_image_url	URL de la miniature
type	photo, video, animated_gif
duration_ms	Durée de la vidéo
height, width	Dimensions
alt_text	Texte pour l’accessibilité

​

Exemple avec des champs

cURL

shellscript

curl "https://api.x.com/2/tweets/1234567890?\
tweet.fields=created_at,public_metrics,entities&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

​

Modifications de Publications

Les Publications peuvent être modifiées jusqu’à 5 fois dans les 30 minutes suivant leur création.

​

Comment ça fonctionne

• Chaque modification crée un nouvel identifiant de Publication
• edit_history_tweet_ids contient toutes les versions (de la plus ancienne à la plus récente)
• L’endpoint renvoie toujours la version la plus récente

​

Exemple de réponse

{
  "data": {
    "id": "1234567893",
    "text": "Hello world! (edited twice)",
    "edit_history_tweet_ids": [
      "1234567890",
      "1234567891",
      "1234567893"
    ]
  }
}

Les Publications récupérées après expiration de leur fenêtre de modification de 30 minutes représentent la version finale. Pour les cas d’usage en temps réel, gardez à l’esprit que les Publications récemment publiées peuvent encore être modifiées.

---

​

Gestion des erreurs

​

Erreurs courantes

Statut	Erreur	Solution
400	Requête invalide	Vérifiez le format des paramètres
401	Non autorisé	Vérifiez vos informations d’authentification
403	Accès interdit	Vérifiez les autorisations de l’App
404	Introuvable	Publication supprimée ou inexistante
429	Trop de requêtes	Patientez puis réessayez (voir les limites de taux)

​

Publications supprimées ou protégées

Si une Publication est supprimée ou provient d’un compte protégé que vous ne suivez pas :

• La recherche d’une seule Publication renvoie un code d’état HTTP 404
• La recherche de plusieurs Publications omet cette Publication des résultats et renvoie un tableau errors

{
  "data": [
    { "id": "1234567890", "text": "Available post" }
  ],
  "errors": [
    {
      "resource_id": "1234567891",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [1234567891]."
    }
  ]
}

---

​

Bonnes pratiques

Regrouper les requêtes

Utilisez l’endpoint multi-Publications pour récupérer jusqu’à 100 Publications en une seule fois, et ainsi réduire le nombre d’appels API.

Ne demander que les champs nécessaires

Indiquez uniquement les champs dont vous avez besoin afin de minimiser la taille des réponses et le temps de traitement.

Mettre les réponses en cache

Mettez en cache les données des Publications en local pour réduire les requêtes répétées pour un même contenu.

Gérer les modifications

Pour les applications en temps réel, envisagez de récupérer à nouveau les Publications après la fenêtre d’édition de 30 minutes.

---

​

Prochaines étapes

Référence de l’API

Documentation complète de l’endpoint

Dictionnaire de données

Tous les objets et champs disponibles

Exemples de code

Exemples de code fonctionnels

Gestion des erreurs

Gérez les erreurs proprement