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.comoutwitter.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
| Ressource | Endpoint | Entrée publique acceptée | Usage typique |
|---|---|---|---|
| Profils | /v1/x/profiles | Noms d’utilisateur, avec ou sans @ | Identité publique et compteurs visibles |
| Posts | /v1/x/posts | URL de statuts x.com ou twitter.com | Un post connu |
| Posts d’un utilisateur | /v1/x/user-posts | Noms d’utilisateur | Posts publics récents d’un compte |
| Recherche | /v1/x/search | Requête | Découverte de posts publics Latest ou Top |
| Réponses | /v1/x/post-replies | URL de statuts | Réponses à un post connu |
| Citations | /v1/x/post-quotes | URL de statuts | Posts de citation d’un post connu |
Également disponibles :
post-retweeterspour des URL de statuts publics.followers-listetfollowing-listpour des noms d’utilisateur, avecresults_limitde 200 à 2 000 par pas de 200.trendspour des WOEID numériques.
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 :
- Acceptez les noms d’utilisateur avec ou sans
@, puis stockez un seul nom d’utilisateur canonique. - Acceptez les hôtes
x.comettwitter.com. Exigez un chemin numérique/status/{id}pour les endpoints qui portent sur des posts. - 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.
- Dédupliquez les noms d’utilisateur sans tenir compte de la casse et les posts par ID de statut.
- Rejetez les requêtes et les noms d’utilisateur vides avant l’envoi.
- 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
platformdoit être égal àx.resourcedoit 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-postset 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 raisonnable | Raison |
|---|---|---|
| Profil | Hebdomadaire ou mensuelle | La bio et les champs d’identité évoluent lentement |
| Post connu | Horaire à quotidienne tant qu’il est actif | Les métriques publiques évoluent vite |
| Fenêtre de posts d’un utilisateur | Horaire à quotidienne pour la surveillance | Les timelines sont délimitées et classées |
| Recherche | Selon un calendrier adapté à la requête | latest et top ne sont pas des archives |
| Réponses / citations | Horaire tant qu’un post est actif | Les liens de conversation arrivent par vagues |
| Abonnés / abonnements | Hebdomadaire | Les listes sont volumineuses et paginées par pas de 200 |
| Tendances | Horaire ou plusieurs fois par jour | Les 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