XTwitterScrapingTutoriel API

Comment rechercher et collecter des posts X/Twitter avec une API

Collectez des profils, posts, timelines, recherches, réponses et citations publics sur X avec des endpoints asynchrones et du JSON normalisé.

SocQMis à jour le 10 septembre 202610 min de lecture

Dans le navigateur, X ressemble toujours à une timeline. Le contrat de données publiques est plus étroit : un nom d’utilisateur n’est pas l’URL d’un post, une citation n’est pas un repost, une réponse n’est pas une citation, et un post supprimé ou protégé doit échouer proprement au lieu de devenir un enregistrement vide.

Ce tutoriel construit un workflow de production avec les API X de SocQ. Il couvre l’accès officiel et l’accès public, le routage des endpoints, l’hygiène des entrées, les tâches asynchrones, le sens des champs, la cadence d’actualisation et l’usage responsable.

Réponse rapide : envoyez des noms d’utilisateur, des URL de statuts x.com ou twitter.com, ou une requête de recherche à POST /v1/x/{resource}, conservez l’ID de tâche et interrogez /v1/tasks/{id}. Ne fusionnez pas citations, reposts et réponses dans une même table sans champ qui distingue la ressource.

API X officielle ou API de données publiques ?

L’API X officielle est payante et soumise à autorisation. C’est le bon produit lorsque vous devez publier, envoyer des messages privés, gérer des publicités, suivre ou aimer en tant qu’utilisateur, ou consommer des flux en continu et d’autres surfaces autorisées par compte. L’accès et les prix évoluent : considérez la documentation développeur actuelle comme la référence pour les produits d’écriture et de partenariat.

SocQ est une couche de lecture publique pour des profils pris en charge, des posts connus, des fenêtres de posts d’un utilisateur, la recherche, les liens de conversation et les tendances. Il ne s’authentifie pas comme un utilisateur X et ne remplace ni la publication officielle ni la publicité. Pour les tarifs et le positionnement des fournisseurs, lisez alternatives aux API Twitter, API de scraping Twitter et alternatives à TwitterAPI.io. Choisissez le modèle d’accès avant de choisir un endpoint.

Choisir le bon endpoint X

RessourceEndpointEntrée publique acceptéeUsage typique
Profils/v1/x/profilesNoms d’utilisateur, avec ou sans @Identité publique et compteurs visibles
Posts/v1/x/postsURL de statuts x.com ou twitter.comUn post connu
Posts d’un utilisateur/v1/x/user-postsNoms d’utilisateurPosts publics récents d’un compte
Recherche/v1/x/searchRequêteDécouverte de posts publics Latest ou Top
Réponses/v1/x/post-repliesURL de statutsRéponses à un post connu
Citations/v1/x/post-quotesURL de statutsPosts de citation d’un post connu

Également disponibles :

Les citations, les reposts et les réponses sont des ressources différentes. Une citation a son propre texte. Une liste de reposteurs est un ensemble de profils. Une réponse est un post qui appartient à une conversation. Ne les traitez pas par upsert comme s’il s’agissait du même objet.

Normaliser les noms d’utilisateur, les URL et les requêtes

Conservez la valeur soumise, puis nettoyez une copie :

  1. Acceptez les noms d’utilisateur avec ou sans @, puis stockez un seul nom d’utilisateur canonique.
  2. Acceptez les hôtes x.com et twitter.com. Exigez un chemin numérique /status/{id} pour les endpoints qui portent sur des posts.
  3. Supprimez les paramètres de requête de suivi. N’exigez pas d’hôte mobile ou de langue particulier si l’ID du statut est intact.
  4. Dédupliquez les noms d’utilisateur sans tenir compte de la casse et les posts par ID de statut.
  5. Rejetez les requêtes et les noms d’utilisateur vides avant l’envoi.
  6. Conservez les expressions de recherche dans la ligne de provenance afin que les analystes puissent expliquer pourquoi un post est entré dans le jeu de données.

user-posts et search acceptent results_limit de 20 à 2 000 par pas de 20. Le sort_by de la recherche vaut latest ou top. post-replies accepte aussi sort_by valant relevance, latest ou likes.

Soumettre une tâche de collecte

Collecter des profils :

curl -X POST "https://api.socq.ai/v1/x/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","@github"]}'

Collecter des posts connus depuis l’un ou l’autre nom d’hôte :

curl -X POST "https://api.socq.ai/v1/x/posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"]}'

Collecter une fenêtre de posts d’un utilisateur :

curl -X POST "https://api.socq.ai/v1/x/user-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["openai","github"],"results_limit":40}'

Rechercher des posts publics :

curl -X POST "https://api.socq.ai/v1/x/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI lang:en","results_limit":100,"sort_by":"latest"}'

Collecter les réponses et les citations dans des tâches séparées :

curl -X POST "https://api.socq.ai/v1/x/post-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20,"sort_by":"latest"}'
curl -X POST "https://api.socq.ai/v1/x/post-quotes" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/X/status/2073395918011789670"],"results_limit":20}'

Conservez l’ID de tâche renvoyé avec le nom de la ressource et les entrées canoniques.

Interroger la tâche sans créer de doublons

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Considérez queued et running comme des états normaux. Utilisez un backoff exponentiel. Lorsque la tâche aboutit, lisez data.results.items et suivez next_cursor tant que has_more vaut true.

Un worker robuste doit conserver :

  • L’ID du lot et l’ID de tâche SocQ.
  • La ressource et les noms d’utilisateur, URL ou requête canoniques.
  • Les heures de soumission et de fin.
  • Le statut final et la catégorie d’erreur.
  • Le dernier curseur de résultats traité.

Le redémarrage d’un worker n’est pas une raison de soumettre à nouveau la même recherche.

Comprendre les champs renvoyés

Les enregistrements partagent id, platform, resource, type, url, created_at, collected_at et extra.

Un profil comprend username, name, description, avatar_url, cover_url, is_verified, is_private et des métriques visibles. Les comptes protégés ne sont pas une cible de données publiques.

Un post comprend text, language, author, des métriques visibles, media, hashtags et mentions lorsqu’ils sont publics. Utilisez id comme clé d’entité de préférence et l’URL du statut comme preuve de provenance.

Les réponses et les citations reprennent la structure d’un post. Les reposteurs reprennent celle d’un profil. Les tendances sont des lignes de découverte rattachées à un lieu, pas des posts.

Les posts supprimés et privés doivent échouer au niveau de l’entrée ou de la tâche. N’insérez pas de post vide, n’inventez pas de zéros d’engagement et ne réutilisez pas collected_at à la place de created_at.

Les résultats de recherche sont une découverte classée. latest et top sont deux ordres différents d’une fenêtre délimitée, pas une archive historique complète.

Worker Python pour les profils, les posts et la recherche

import time
import requests

BASE = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

def collect(resource, payload):
    created = requests.post(
        f"{BASE}/x/{resource}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    created.raise_for_status()
    task_id = created.json()["data"]["task_id"]

    delay = 2
    while True:
        response = requests.get(
            f"{BASE}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["data"]

        if task["status"] == "succeeded":
            return task["results"]["items"]
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

profiles = collect("profiles", {"usernames": ["openai"]})
hits = collect("search", {
    "query": "AI lang:en",
    "results_limit": 40,
    "sort_by": "latest",
})

Ajoutez la pagination par curseur, des nouvelles tentatives bornées pour les délais d’expiration et les réponses 5xx pouvant être retentées, ainsi que des upserts idempotents avant la mise en production.

Modéliser séparément les posts et les instantanés de métriques

L’identité d’un post et ses métriques évoluent à des rythmes différents.

x_entity
  resource
  platform_id
  canonical_url_or_username
  text_or_description
  author_id
  created_at
  first_seen_at
  last_seen_at

x_snapshot
  resource
  platform_id
  collected_at
  likes_count
  replies_count
  reposts_count
  quotes_count
  source_task_id

Faites un upsert par resource + id. Ne stockez les citations, les réponses et les posts sources dans la même table de posts que si resource reste une colonne obligatoire. Conservez les reposteurs dans une table de profils ou de relations.

Ne calculez pas la croissance des citations à partir d’un instantané de reposteurs. Les métriques ne sont pas interchangeables.

Valider avant le stockage

  • platform doit être égal à x.
  • resource doit correspondre à l’endpoint.
  • Les URL de statuts doivent contenir un ID numérique après /status/ lorsque la ressource porte sur des posts.
  • Les noms d’utilisateur des auteurs doivent correspondre au compte soumis lorsque la ressource est user-posts et que le champ est présent.
  • Les compteurs doivent être des nombres positifs ou nuls, ou null.
  • Les horodatages doivent pouvoir être interprétés.
  • Une entrée privée ou supprimée en échec ne doit pas devenir un post vide réussi.

Conservez les lignes invalides en quarantaine avec la charge utile brute de la tâche.

Choisir un calendrier d’actualisation par entité

EntitéCadence de départ raisonnableRaison
ProfilHebdomadaire ou mensuelleLa bio et les champs d’identité évoluent lentement
Post connuHoraire à quotidienne tant qu’il est actifLes métriques publiques évoluent vite
Fenêtre de posts d’un utilisateurHoraire à quotidienne pour la surveillanceLes timelines sont délimitées et classées
RechercheSelon un calendrier adapté à la requêtelatest et top ne sont pas des archives
Réponses / citationsHoraire tant qu’un post est actifLes liens de conversation arrivent par vagues
Abonnés / abonnementsHebdomadaireLes listes sont volumineuses et paginées par pas de 200
TendancesHoraire ou plusieurs fois par jourLes ensembles de WOEID tournent

Réduisez la collecte lorsque la question métier n’exige pas un instantané plus récent.

Modes de défaillance courants

L’URL d’un post ne renvoie rien

Vérifiez que l’URL est publique, toujours disponible et qu’elle contient /status/{id}. Les posts supprimés et protégés doivent échouer proprement. Conservez l’erreur au niveau de l’entrée.

La recherche semble incomplète

results_limit plafonne la requête. Le classement, l’indexation et le choix entre latest et top modifient tous la page. Stockez la requête et le tri avec les enregistrements.

Des citations ont été stockées comme des reposts

Ce sont des endpoints et des objets différents. Gardez resource dans la clé primaire.

Les tâches d’abonnés rejettent la limite

Les abonnés et les abonnements acceptent de 200 à 2 000 par incréments de 200. Les posts d’un utilisateur et la recherche utilisent des pas de 20.

Les métriques diffèrent de celles du navigateur

Les compteurs publics sont des instantanés. Ils peuvent être retardés, arrondis ou masqués. Comparez collected_at avant d’incriminer le parseur.

Le même utilisateur apparaît deux fois

Canonisez les noms d’utilisateur et privilégiez un ID public stable. Tenez une table d’alias lorsqu’un compte change de nom.

Usage responsable des données X

Ne collectez que les champs publics nécessaires à une finalité légitime. Ne contournez ni les comptes protégés, ni les blocages, ni les murs de connexion, ni les autres contrôles d’accès. Évitez le profilage individuel de données sensibles et les décisions automatisées susceptibles d’affecter sensiblement une personne sans garanties.

Les données X peuvent être des données personnelles. Établissez une base légale lorsque c’est requis, définissez des règles de conservation et de suppression, protégez les clés API et les exports, et faites examiner les conditions actuelles de X par des conseillers qualifiés. Une API de données publiques n’accorde pas de licence pour republier des posts ou des médias.

FAQ

Le scraping de X ou de Twitter est-il légal ?

Il n’existe pas de réponse universelle. Cela dépend de la juridiction, des données, de la méthode, de la finalité, du contrat et des garanties mises en place. Ce tutoriel ne constitue pas un avis juridique.

Cela remplace-t-il l’API X officielle ?

Non. L’accès officiel reste nécessaire pour la publication, les messages privés, la publicité, les flux en continu et les autres actions soumises à autorisation. SocQ couvre les lectures publiques prises en charge.

Puis-je collecter des posts privés ou supprimés ?

Non. Ces entrées doivent échouer proprement. Ne contournez pas la protection.

Les citations sont-elles identiques aux reposts ?

Non. Les citations sont des posts. Les reposteurs sont des profils. Les réponses sont une troisième ressource.

La recherche renvoie-t-elle un historique complet ?

Non. Elle renvoie une fenêtre délimitée et ordonnée pour une requête.

Quelle clé utiliser pour la déduplication ?

Privilégiez resource + id. Repliez-vous sur une URL de statut normalisée ou un nom d’utilisateur lorsque l’ID public est manquant.

X API

Tester le workflow avec une URL publique X

Envoyez des entrées publiques et recevez des enregistrements normalisés, avec un contexte de source traçable.

Découvrir les API X