Guide d'intégration

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

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Récupérer un utilisateur par son nom d’utilisateur
response = client.users.get_by_username("XDevelopers")
print(response.data)

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

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

const response = await client.users.getByUsername("XDevelopers");
console.log(response.data);

Authentification en contexte utilisateur

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

cURL

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

from xdk import Client

# Utilisation d'un jeton d'accès utilisateur OAuth 2.0
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Obtenir le profil de l'utilisateur authentifié
response = client.users.get_me()
print(response.data)

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

// Utilisation d'un jeton d'accès utilisateur OAuth 2.0
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const response = await client.users.getMe();
console.log(response.data);

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Récupérer un utilisateur avec des champs supplémentaires et des expansions
response = client.users.get_by_username(
    "XDevelopers",
    user_fields=["created_at", "description", "public_metrics", "verified"],
    expansions=["pinned_tweet_id"],
    tweet_fields=["created_at", "public_metrics"]
)

print(response.data)
print(response.includes)  # Contient le tweet épinglé étendu

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

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

const response = await client.users.getByUsername("XDevelopers", {
  userFields: ["created_at", "description", "public_metrics", "verified"],
  expansions: ["pinned_tweet_id"],
  tweetFields: ["created_at", "public_metrics"],
});

console.log(response.data);
console.log(response.includes); // Contient le tweet épinglé étendu

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)

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Récupérer plusieurs utilisateurs par identifiants
response = client.users.get_users(
    ids=["2244994945", "783214", "6253282"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

# Récupérer plusieurs utilisateurs par noms d'utilisateur
response = client.users.get_users_by_usernames(
    usernames=["XDevelopers", "X", "XAPI"],
    user_fields=["username", "verified"]
)
for user in response.data:
    print(f"{user.username}: {user.verified}")

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

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

// Récupérer plusieurs utilisateurs par identifiants
const byIds = await client.users.getUsers({
  ids: ["2244994945", "783214", "6253282"],
  userFields: ["username", "verified"],
});
byIds.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

// Récupérer plusieurs utilisateurs par noms d'utilisateur
const byUsernames = await client.users.getUsersByUsernames({
  usernames: ["XDevelopers", "X", "XAPI"],
  userFields: ["username", "verified"],
});
byUsernames.data.forEach((user) => {
  console.log(`${user.username}: ${user.verified}`);
});

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