Guide d'intégration

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

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Récupérer une Publication avec des champs et des expansions supplémentaires
response = client.posts.get(
    "1234567890",
    tweet_fields=["created_at", "public_metrics", "entities"],
    expansions=["author_id", "attachments.media_keys"],
    user_fields=["username", "verified"],
    media_fields=["url", "type"]
)

print(response.data)
print(response.includes)  # Contient les objets utilisateur et média étendus

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

const response = await client.posts.get("1234567890", {
  tweetFields: ["created_at", "public_metrics", "entities"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
});

console.log(response.data);
console.log(response.includes); // Contient les objets utilisateur et média étendus

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