x/
trends

Collectez les tendances publiques actuelles de X pour un ou plusieurs WOEID numériques, avec rang source, requête, description, contexte géographique et heure de collecte.

X Trends API

Instantanés par WOEID
Rang source
Contexte géographique
0,5 crédit par résultat
Prêt
README

Par SocQ · Mis à jour le

X Trends

Les tendances X forment un instantané, rattaché à un lieu, des sujets publics disponibles pour un WOEID numérique ; le nom d’origine, le rang, la requête, la description et l’heure de collecte y restent réunis. Cette structure permet de repérer des sujets régionaux et de les observer à intervalles répétés, tout en rappelant que chaque enregistrement reflète le moment de la collecte et non une série historique de tendances.

Fonctionnalités de la X Trends API

  • Collecte par lieuDemandez les tendances publiques actuelles d’un ou plusieurs WOEID numériques connus, et gardez l’identifiant d’origine dans extra.woeid.
  • Rang d’origine conservéLe rang fourni en amont reste dans metrics.rank lorsqu’il est disponible, sans être remplacé par un score calculé par SocQ.
  • Contexte utile pour chaque tendanceRecevez le nom de la tendance avec la requête en amont et la description du fournisseur lorsque ces champs sont exposés.
  • Plafonds indépendants selon le lieuresults_limit s’applique séparément à chaque WOEID envoyé, et l’ensemble de tendances actuellement disponible pour chaque lieu n’est collecté qu’une fois.

Paramètres de la X Trends API

ParamètresObligatoireDescription
woeidsObligatoireTableau obligatoire d’un ou plusieurs identifiants de lieux X connus, chacun représenté par une chaîne numérique non vide.
results_limitFacultatifPlafond entier facultatif, appliqué séparément à chaque WOEID. La valeur par défaut est 100 et les valeurs de 20 à 2 000 sont acceptées.

Comment utiliser la X Trends API

Partez de WOEID numériques que vous connaissez déjà, fixez un plafond par lieu et traitez les enregistrements renvoyés comme un instantané pris au moment de la collecte.

  1. Saisissez un ou plusieurs WOEID connus sous forme de chaînes numériques ; cet endpoint ne convertit pas les noms de lieux.
  2. Choisissez un entier results_limit de 20 à 2 000, ou gardez la valeur par défaut de 100 par WOEID.
  3. Envoyez la requête en POST à /v1/x/trends, puis interrogez /v1/tasks/{task_id} jusqu’à la réussite de la tâche.
  4. Lisez data.results.items et suivez le next_cursor du résultat de la tâche tant que has_more vaut true.
curl -X POST "https://api.socq.ai/v1/x/trends" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"woeids":["1"],"results_limit":100}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Cas d’usage de la X Trends API

  • Surveiller les sujets d’un marché connu : Collectez les noms, rangs et descriptions actuels associés à un identifiant de lieu que votre système de veille gère déjà.
  • Constituer des instantanés d’observation récurrents : Interrogez le même WOEID selon le calendrier de votre choix et stockez collected_at avec chaque résultat pour analyser ensuite les changements.
  • Alimenter une file de revue des sujets : Appuyez-vous sur le nom, la requête, le rang et la description renvoyés pour hiérarchiser les sujets publics à examiner par des analystes ou à transmettre à un workflow de découverte en aval.

Conseils d’expert pour la X Trends API

  • Préparez des WOEID numériques avant d’envoyer une tâche : les noms de lieux et les localisations en texte libre ne sont pas acceptés.
  • La valeur par défaut 1 reprend l’exemple de requête publié par le backend ; remplacez-la par l’identifiant qui correspond à votre périmètre.
  • Voyez results_limit comme un plafond par WOEID, car un ensemble de tendances actuel peut contenir moins de lignes que demandé.
  • Lancez les lieux qui se recoupent dans des tâches séparées si vous tenez à garder chaque association entre tendance et lieu, car des noms de tendance identiques peuvent être dédoublonnés au sein d’une même tâche.
  • Prenez collected_at comme heure d’observation ; created_at vaut null parce que la source n’expose pas d’horodatage de création des tendances.
  • Les curseurs de résultat d’une tâche parcourent des enregistrements déjà sauvegardés et ne demandent pas au fournisseur une nouvelle page de tendances.

En complément de la X Trends API, utilisez ces API lorsque vous avez besoin d’un autre type de données publiques X.

  • Twitter Tweet Scraper API — Récupérez le texte des posts publics, auteurs, l’engagement, médias, hashtags, mentions et relations de conversation à partir d’URL de statuts x.com ou twitter.com.
  • Twitter Profile Scraper API — Récupérez par nom d’utilisateur l’identité publique d’un compte, ses biographies, avatars, images de couverture, statut du compte et statistiques d’audience visibles.
  • Twitter User Tweets Scraper API — Collectez par nom d’utilisateur les posts publics récents, auteurs, médias, hashtags, mentions et l’engagement, hors réponses.
  • Twitter Search API — Trouvez des posts publics par expression de recherche, avec tri par récents ou populaires et limite de résultats configurable.
  • Twitter User Search API — Trouvez des comptes X publics par mot-clé.
  • X Communities Search API — Trouvez des communautés par mot-clé, avec le nombre de membres et un lien utilisable par les endpoints de membres et de posts.

Explorer d’autres plateformes

Combinez les données X avec les données publiques d’autres plateformes sociales prises en charge.

X Trends API — FAQ

X Trends API est une interface programmatique pour collecter des instantanés des tendances publiques actuelles de X, par WOEID numérique.

Indiquez un ou plusieurs identifiants de lieux connus sous forme de chaînes numériques. L’endpoint ne traduit pas le nom d’une ville ou d’un pays en WOEID.

Il vaut 100 par défaut, accepte les entiers de 20 à 2 000 et s’applique séparément à chaque WOEID. La source peut exposer moins de tendances actuelles que le plafond demandé.

Un enregistrement contient le nom de la tendance en id et text, un rang en amont lorsqu’il existe, collected_at, ainsi que des champs extra pour le WOEID, la requête et la description lorsqu’ils sont disponibles.

Non. Il renvoie un instantané actuel pour chaque WOEID demandé ; pour obtenir un historique, planifiez des exécutions répétées et stockez-les dans votre propre système.

Les enregistrements sauvegardés sont dédoublonnés par nom de tendance normalisé au sein d’une tâche. Si le même nom se retrouve dans plusieurs lieux envoyés, le premier enregistrement sauvegardé ne peut garder qu’une seule valeur extra.woeid.

Chaque tendance normalisée enregistrée avec succès coûte 0,5 crédit SocQ. L’estimation utilise results_limit pour chaque WOEID envoyé, et les crédits prélevés d’avance mais non utilisés sont remboursés une fois la tâche réglée.