Guide d'intégration

Concepts clés et bonnes pratiques pour intégrer la recherche d’utilisateurs

Ce guide présente les concepts clés nécessaires pour intégrer les points de terminaison de recherche d’utilisateurs à votre application.

---

​

Authentification

Tous les endpoints de X API v2 nécessitent une authentification. Choisissez la méthode la mieux adaptée à votre cas d’usage :

Méthode	Idéale 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	Apps destinées aux utilisateurs finaux	Oui (pour les données de l’utilisateur autorisé)
OAuth 1.0a User Context	Anciennes intégrations	Oui (pour les données de l’utilisateur autorisé)

​

Authentification App-only

Pour les données publiques d’utilisateurs, utilisez un jeton Bearer :

cURL

shellscript

curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Authentification en contexte utilisateur

Requise pour le point de terminaison de l’utilisateur authentifié (/2/users/me) :

cURL

shellscript

curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Le point de terminaison /2/users/me ne fonctionne qu’avec l’authentification en contexte utilisateur. Les jetons App-Only renverront une erreur.

---

​

Champs et expansions

L’API X v2 renvoie par défaut un ensemble minimal de données. Utilisez fields et expansions pour obtenir exactement ce dont vous avez besoin.

​

Réponse par défaut

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

​

Champs disponibles

user.fields

Champ	Description
created_at	Horodatage de création du compte
description	Bio de l’utilisateur
entities	URL analysées dans la bio
location	Lieu défini par l’utilisateur
pinned_tweet_id	ID de la Publication épinglée
profile_image_url	URL de l’avatar
protected	Indique si le compte est protégé
public_metrics	Nombre d’abonnés / d’abonnements
url	URL du site Web
verified	Statut de vérification
withheld	Informations relatives à la restriction de diffusion

tweet.fields (nécessite l’expansion pinned_tweet_id)

Champ	Description
created_at	Horodatage de création de la Publication
text	Contenu de la Publication
public_metrics	Nombre d’engagements
entities	Hashtags, mentions, URL

​

Exemple avec des champs

cURL

shellscript

curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Réponse avec expansions

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Bienvenue sur la plateforme de développement X !",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

Guide des champs et des expansions

En savoir plus sur la personnalisation des réponses

---

​

Recherches groupées

Recherchez plusieurs utilisateurs en une seule requête :

cURL (par identifiants)

shellscript

curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Les requêtes groupées sont limitées à 100 utilisateurs. Utilisez plusieurs requêtes pour des ensembles de données plus volumineux.

---

​

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	L’utilisateur n’existe pas ou a été suspendu
429	Trop de requêtes	Patientez puis réessayez (voir limites de taux)

​

Utilisateurs suspendus ou supprimés

Si un utilisateur est suspendu ou supprimé :

• La recherche d’un seul utilisateur renvoie un 404
• La recherche de plusieurs utilisateurs omet cet utilisateur des résultats et inclut un tableau errors

{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

​

Utilisateurs protégés

Pour les comptes protégés que vous ne suivez pas :

• Les informations de base (id, nom, nom d’utilisateur) sont disponibles
• Le contenu protégé (Publication épinglée) peut être restreint
• protected: true indique l’état du compte

---

​

Bonnes pratiques

Regrouper les requêtes

Utilisez des endpoints multi-utilisateurs pour récupérer jusqu’à 100 comptes à la fois et réduire le nombre d’appels à l’API.

Ne demander que les champs nécessaires

Indiquez uniquement les champs dont vous avez besoin afin de minimiser la taille de la réponse.

Mettre en cache les données utilisateur

Mettez en cache les profils utilisateur en local pour réduire les requêtes répétées.

Gérer les erreurs de manière robuste

Vérifiez la présence d’erreurs partielles dans les réponses par lot.

---

​

Prochaines étapes

Référence de l’API

Documentation complète de l’endpoint

Dictionnaire des données

Tous les objets et champs disponibles

Exemples de code

Exemples de code prêts à l’emploi

Gestion des erreurs

Gérez les erreurs proprement