XCommunautés TwitterPosts de communautéCSVTutoriel API

Comment scraper les posts des communautés Twitter/X avec une API

Collectez les posts des communautés Twitter/X avec SocQ. Exportez en JSON et CSV avec attribution des sources, métadonnées et exemples de pagination pour une recherche thématique fondée sur les sources.

SocQMis à jour le 16 octobre 20269 min de lecture

Collectez les discussions des communautés Twitter/X avec SocQ et conservez ensemble le texte des posts, les auteurs, les heures de publication et les sources. Transformez les questions récurrentes en idées de sujets, avec les posts d’origine rattachés à chaque constat pour une revue ultérieure.

Ce tutoriel utilise X Community Posts de SocQ pour collecter les posts et X Community pour interroger la description et les règles. Les exemples produisent du JSON qui préserve les sources et un export CSV organisé par communauté.

Réponse rapide : envoyez des liens x.com/i/communities/{id} à POST /v1/x/community-posts, enregistrez l’ID de tâche et lisez toutes les pages de résultats une fois la tâche réussie. Interrogez les métadonnées via POST /v1/x/community avec le même lien. Rattachez la communauté d’entrée à chaque post pour relier les métadonnées et les discussions.

Utiliser l’URL d’une communauté publique comme entrée

Utilisez une URL de cette forme, en la remplaçant par la communauté publique que vous voulez étudier :

https://x.com/i/communities/1493446837214187523

Le segment numérique est l’ID de la communauté. Les deux endpoints de communauté prennent une URL /i/communities/{numeric_id} complète.

Si vous ne connaissez que le nom de la communauté, trouvez d’abord son URL publique et envoyez le lien dans urls.

Conservez l’URL soumise, l’ID numérique de la communauté, l’heure de publication (published_at) et l’heure de collecte (collected_at). Rapprochez les variantes x.com et twitter.com prises en charge à partir de l’ID de la communauté, et gardez séparées les communautés dont les ID diffèrent, même si leurs noms sont identiques.

Collecter les posts du flux d’une communauté Twitter/X

Définissez SOCQ_API_KEY et soumettez une tâche plafonnée à 40 posts par communauté :

curl -X POST "https://api.socq.ai/v1/x/community-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://x.com/i/communities/1493446837214187523"],
    "results_limit": 40
  }'

La réponse fournit data.task_id. Enregistrez-le, puis interrogez la tâche existante :

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

Patientez entre deux requêtes tant que la tâche est queued, running ou retrying. Une tâche failed expose data.error_message. Dès qu’elle est succeeded, les enregistrements de posts se trouvent dans data.results.items.

Community Posts renvoie les enregistrements par ordre de création. Pour un rapport trié par mentions « J’aime » ou par commentaires, triez localement les enregistrements collectés et indiquez que le classement porte sur un échantillon.

Comprendre les limites par communauté

results_limit vaut 100 par défaut et accepte les multiples de 20 de 20 à 2 000, par exemple 20, 40, 60 et 100.

Le plafond s’applique à chaque communauté d’entrée. Deux URL avec results_limit=40 demandent jusqu’à 40 posts chacune ; le nombre réel dépend des résultats dédupliqués enregistrés.

Le paramètre limit de l’interrogation de tâche définit le nombre d’enregistrements enregistrés lus par page, et next_cursor identifie la page suivante. Le results_limit soumis fixe le plafond de collecte.

Savoir quelles données de communauté vous obtenez

RessourceChamps standardQuestion de recherche
Communityname, text, rules, join_policy, invites_policyQuelle description, quelles règles et quelles politiques de participation ont été enregistrées ?
Compteurs de la communautémetrics.members_count, metrics.moderators_countCombien de membres et de modérateurs la source indique-t-elle ?
Community Postsid, text, author, published_at, mediaQuelles discussions figurent dans la fenêtre collectée ?
Métriques des postsNombres disponibles de mentions « J’aime », de commentaires, de partages et de vuesComment les posts échantillonnés se comparent-ils au moment de la collecte ?

La requête de métadonnées est distincte :

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

Récupérez les métadonnées avec leur propre ID de tâche. Les totaux de membres et de modérateurs décrivent l’échelle de la communauté, tandis que le nombre de vues d’un post enregistre les vues de ce post. Le nombre d’auteurs actifs et la portée unique exigent leurs propres mesures.

Null signifie que la source a omis une mesure ; 0 est un compteur renvoyé égal à zéro. Conservez ces deux valeurs de façon distincte dans votre export.

Exporter les posts d’une communauté en JSON et CSV avec Python

Le workflow suivant utilise la bibliothèque standard de Python. Enregistrez cet utilitaire de tâches sous le nom socq_collect.py :

import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}

def api(method, path, payload=None):
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    request = Request(
        BASE + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("code") != 200:
        raise RuntimeError(result)
    return result["data"]

def collect(endpoint, payload):
    task_id = api("POST", "/" + endpoint, payload)["task_id"]
    print("Task:", task_id, flush=True)
    path = "/tasks/" + task_id
    deadline = time.monotonic() + 600
    data = api("GET", path + "?limit=100")
    while data["status"] in PENDING:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
        time.sleep(2)
        data = api("GET", path + "?limit=100")
    if data["status"] != "succeeded":
        raise RuntimeError(data.get("error_message") or data["status"])

    items, seen_cursors = [], set()
    while True:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume pagination for " + task_id)
        page = data["results"]
        items.extend(page["items"])
        if not page["has_more"]:
            return task_id, items
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated result cursor")
        seen_cursors.add(cursor)
        data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
        if data["status"] != "succeeded":
            raise RuntimeError("Task is not ready for result pagination")

L’utilitaire affiche chaque ID de tâche, attend jusqu’à dix minutes et lit chaque page de résultats enregistrée. Après un délai d’expiration côté client, conservez l’ID et reprenez l’interrogation de cette tâche.

Enregistrez ensuite export_communities.py à côté :

import csv
import json
import sys
from urllib.parse import urlparse
from socq_collect import collect

urls = list(dict.fromkeys(sys.argv[1:]))
if not urls:
    raise SystemExit("Usage: python3 export_communities.py COMMUNITY_URL [COMMUNITY_URL...]")

def cell(value):
    text = "" if value is None else str(value)
    return "'" + text if text.lstrip().startswith(("=", "+", "-", "@")) else text

fields = ["community_id", "community_url", "post_id", "post_url", "text",
          "author_id", "author_username", "published_at", "collected_at",
          "likes_count", "comments_count", "shares_count", "views_count"]
bundles, seen = [], set()
with open("community-posts.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=fields)
    writer.writeheader()
    for url in urls:
        metadata_task, communities = collect("x/community", {"urls": [url]})
        posts_task, posts = collect("x/community-posts", {
            "urls": [url], "results_limit": 40,
        })
        bundles.append({
            "input_url": url, "metadata_task_id": metadata_task,
            "posts_task_id": posts_task, "communities": communities, "posts": posts,
        })
        # Save completed collections before processing another community.
        with open("community-results.json", "w", encoding="utf-8") as saved:
            json.dump(bundles, saved, ensure_ascii=False, indent=2)
        community_id = urlparse(url).path.rstrip("/").split("/")[-1]
        for post in posts:
            post_id = post.get("id")
            key = (community_id, post_id)
            if post_id and key in seen:
                continue
            if post_id:
                seen.add(key)
            author = post.get("author") or {}
            metrics = post.get("metrics") or {}
            row = {
                "community_id": community_id, "community_url": url,
                "post_id": post_id, "post_url": post.get("url"), "text": post.get("text"),
                "author_id": author.get("id"), "author_username": author.get("username"),
                "published_at": post.get("published_at"),
                "collected_at": post.get("collected_at"),
                **{name: metrics.get(name) for name in
                   ("likes_count", "comments_count", "shares_count", "views_count")},
            }
            writer.writerow({key: cell(value) for key, value in row.items()})

Lancez-le avec une ou plusieurs URL de communautés publiques :

python3 export_communities.py \
  "https://x.com/i/communities/1493446837214187523"

Vous obtenez deux sorties :

  • community-results.json conserve chaque URL d’entrée, les deux ID de tâche, les métadonnées de la communauté et les enregistrements de posts.
  • community-posts.csv fournit une ligne par post renvoyé au sein de chaque communauté, avec la source, l’auteur, les horodatages et les métriques disponibles.

L’exemple crée une tâche de métadonnées et une tâche de posts distinctes pour chaque communauté, en rattachant la communauté d’entrée à ses posts. La source de collecte de chaque enregistrement est ainsi explicite. Utilisez un lot pour une récupération combinée, ou le schéma à communauté unique présenté ici lorsque vous avez besoin de l’attribution de la source post par post.

La déduplication s’appuie sur community_id + post_id. Elle fusionne les lignes répétées au sein d’une communauté et garde séparées les observations d’un même post provenant de communautés différentes. Les enregistrements sans ID de post sont conservés individuellement.

Le programme met à jour les fichiers après chaque communauté terminée. Si une requête ultérieure échoue, les fichiers conservent les communautés déjà traitées. Avant d’utiliser la sortie dans un rapport, vérifiez les entrées terminées et les erreurs consignées.

Garder le JSON comme source des exports pour tableur

Le CSV est pratique pour les relecteurs, mais il aplatit les données. Les règles imbriquées, les médias et les champs d’auteur restent disponibles dans le JSON. Régénérez un autre tableur à partir de ce JSON enregistré lorsque vos colonnes changent.

L’exemple utilise l’écrivain CSV de la bibliothèque standard de Python pour gérer les guillemets, les virgules et les textes multilignes. L’UTF-8 avec marque d’ordre des octets facilite les imports courants dans les tableurs. Le texte public qui ressemble à une formule est échappé dans le CSV ; le JSON préserve le contenu d’origine. Importez les longs ID numériques sous forme de texte pour éviter toute perte de précision dans le tableur.

Utiliser les discussions d’une communauté pour la recherche thématique

Demandez par exemple quelles questions d’accueil reviennent dans les discussions collectées. Regroupez-les par question et conservez les ID des posts qui les étayent pour chaque catégorie.

Lisez d’abord la description et les règles de la communauté. Examinez ensuite ensemble le texte des posts, l’heure de publication et les liens vers les sources. Regroupez les questions récurrentes, les réclamations sur des produits ou les demandes de ressources, et gardez les ID des posts qui les étayent à côté de vos libellés.

Utilisez le workflow de détails d’une communauté pour enregistrer les descriptions et les règles, puis lancez la classification thématique ou le résumé dans votre application.

Présentez un tri local par mentions « J’aime » ou par commentaires comme un « classement au sein de cette capture », avec son heure de collecte et son nombre d’enregistrements. Signalez un post absent d’une capture ultérieure par « non observé dans cette capture » ; interrogez ce post séparément pour vérifier s’il a été supprimé.

Examiner une discussion en particulier

Pour développer une discussion, envoyez l’URL du post renvoyé à X Thread Context et lisez la cible, les posts précédents de la chaîne de réponses et les relations entre réponses.

Pour cette étape suivante, lisez le tutoriel sur le contexte d’un fil Twitter. Si vous n’avez besoin que des réponses à un post connu, utilisez X Post Replies. Si votre point de départ est un compte plutôt qu’une communauté, utilisez X User Posts.

Garder les posts d’origine derrière vos décisions de contenu

Les endpoints de métadonnées et de posts de communauté de SocQ relient l’identification des communautés, la collecte des discussions et la revue des sujets. Le code conserve la communauté source de chaque post et exporte du JSON et du CSV, ce qui permet aux équipes de contenu de relire les questions, d’organiser des exemples et de préparer les entrées de résumés.

Ouvrez Community Posts et collectez votre communauté cible.

Sources et lectures complémentaires

FAQ

Puis-je collecter les posts de plusieurs communautés X ?

Oui. Envoyez plusieurs URL de communautés dans urls. Le plafond de résultats s’applique à chaque URL. L’exemple d’export Python utilise des tâches distinctes pour conserver une communauté d’entrée clairement identifiée pour chaque post.

Cela renvoie-t-il tous les posts jamais publiés dans une communauté ?

Une tâche lit une sélection de posts de la communauté indiquée, plafonnée par results_limit. Les enregistrements renvoyés définissent le périmètre de cette capture. Pour une analyse historique, enregistrez des captures distinctes et indiquez le périmètre de chacune.

Puis-je exporter les membres d’une communauté en plus des posts ?

Community renvoie les métadonnées ainsi que les nombres de membres et de modérateurs ; Community Posts renvoie les posts. Les annuaires de membres individuels constituent des données distinctes et ne sont pas renvoyés par ces endpoints.

En quoi le flux d’une communauté diffère-t-il de la timeline d’un utilisateur ?

Le flux d’une communauté regroupe les posts d’un espace de discussion ; la timeline d’un utilisateur regroupe les posts d’un compte. Utilisez des liens de communauté pour Community Posts et des noms d’utilisateur pour User Posts.

Puis-je choisir un tri Top ou Likes ?

L’endpoint renvoie les posts par ordre de création. Triez l’échantillon par mentions « J’aime » ou par commentaires dans votre application pour obtenir un classement par métrique de cette capture.

La pagination collecte-t-elle les nouveaux posts ?

Le curseur lit la page suivante enregistrée par la tâche d’origine. Soumettez une nouvelle tâche pour une nouvelle observation, puis traitez les enregistrements qui se chevauchent à partir de l’ID du post.

Comment collecter les posts après l’annonce de migration des communautés ?

X a publié une annonce de migration des Communities vers XChat. Envoyez l’URL de la communauté cible à Community Posts et lisez les posts renvoyés une fois la tâche réussie. Consignez séparément les résultats vides et les échecs, et conservez les heures de collecte pour distinguer l’historique enregistré de chaque nouvelle requête.

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