x/
trends

Raccogli le tendenze pubbliche attuali di X per uno o più WOEID numerici, con posizione nella classifica di origine, query, descrizione, contesto geografico e momento della raccolta.

X Trends API

Istantanee per WOEID
Posizione di origine
Contesto geografico
0,5 crediti per risultato
Pronto
README

A cura di SocQ · Aggiornato il

X Trends

Le tendenze di X sono un’istantanea, organizzata per località, degli argomenti pubblici disponibili per un WOEID numerico, con nome di origine, posizione, query, descrizione e momento della raccolta conservati insieme. Questa struttura supporta la scoperta di argomenti regionali e l’osservazione ripetuta, chiarendo che ogni record riflette il momento della raccolta e non una serie storica delle tendenze.

Funzionalità della X Trends API

  • Raccolta per localitàRichiedi le tendenze pubbliche attuali per uno o più WOEID numerici noti e conserva l’identificatore di origine in extra.woeid.
  • Posizione di origine conservataMantieni in metrics.rank la posizione fornita a monte, quando è disponibile, senza sostituirla con un punteggio calcolato da SocQ.
  • Contesto utile della tendenzaRicevi il nome della tendenza con una query e una descrizione del provider a monte, quando questi campi sono esposti.
  • Limiti indipendenti per localitàApplica results_limit separatamente a ogni WOEID inviato, raccogliendo una sola volta l’insieme di tendenze attualmente disponibile per ciascuna località.

Parametri della X Trends API

ParametriObbligatorioDescrizione
woeidsObbligatorioArray obbligatorio di uno o più identificatori di località di X noti, ciascuno rappresentato come stringa numerica non vuota.
results_limitFacoltativoLimite intero facoltativo applicato separatamente a ogni WOEID. Il valore predefinito è 100 e sono accettati valori da 20 a 2.000.

Come usare la X Trends API

Parti dai WOEID numerici che già conosci, scegli un limite per località e considera i record restituiti come un’istantanea del momento della raccolta.

  1. Inserisci uno o più WOEID noti come stringhe numeriche; questo endpoint non risolve i nomi dei luoghi.
  2. Scegli un results_limit intero da 20 a 2.000 oppure mantieni il valore predefinito di 100 per ogni WOEID.
  3. Invia con POST la richiesta a /v1/x/trends, poi interroga /v1/tasks/{task_id} finché l’attività ha successo.
  4. Leggi data.results.items e segui il next_cursor del risultato dell’attività finché has_more è 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

Casi d’uso della X Trends API

  • Osservare gli argomenti di un mercato noto: Raccogli i nomi, le posizioni e le descrizioni attuali associati a un identificatore di località che il tuo sistema di monitoraggio già gestisce.
  • Creare istantanee di osservazione periodiche: Esegui lo stesso WOEID con una pianificazione che controlli tu e salva collected_at con ogni risultato per l’analisi successiva dei cambiamenti.
  • Creare una coda di revisione degli argomenti: Usa nome, query, posizione e descrizione restituiti per dare priorità agli argomenti pubblici da sottoporre ad analisti o a un flusso di scoperta a valle.

Consigli degli esperti per la X Trends API

  • Prepara i WOEID numerici prima di inviare un’attività; i nomi dei luoghi e le località in testo libero non sono accettati.
  • Il valore predefinito 1 segue l’esempio di richiesta pubblicato dal backend; sostituiscilo con l’identificatore che corrisponde all’ambito che ti interessa.
  • Considera results_limit come un tetto per WOEID, perché un insieme di tendenze attuale può contenere meno righe di quelle richieste.
  • Esegui le località sovrapposte in attività separate quando è importante conservare ogni associazione tra tendenza e località, perché nomi di tendenza identici possono essere deduplicati all’interno di una stessa attività.
  • Usa collected_at come momento dell’osservazione; created_at è null perché la fonte non espone un timestamp di creazione della tendenza.
  • I cursori dei risultati dell’attività scorrono record già salvati e non richiedono al provider un’altra pagina di tendenze.

Oltre alla X Trends API, usa queste API quando ti serve un altro tipo di dati pubblici di X.

  • Twitter Tweet Scraper API — Recupera testo dei post pubblici, autori, engagement, media, hashtag, menzioni e relazioni della conversazione dagli URL di stato di x.com o twitter.com.
  • Twitter Profile Scraper API — Recupera identità dell’account pubblico, bio, avatar, immagini di copertina, stato dell’account e statistiche visibili del pubblico a partire dal nome utente.
  • Twitter User Tweets Scraper API — Raccoglie i post pubblici recenti, autori, media, hashtag, menzioni ed engagement a partire dal nome utente, escludendo le risposte.
  • Twitter Search API — Trova post pubblici tramite espressione di ricerca con ordinamento per più recenti o più popolari e un limite di risultati configurabile.
  • Twitter User Search API — Trova account X pubblici per parola chiave.
  • X Communities Search API — Trova community per parola chiave, con numero di membri e link per gli endpoint dei membri e dei post.

Esplora altre piattaforme

Combina i dati di X con i dati pubblici delle altre piattaforme social supportate.

X Trends API — FAQ

X Trends API è un’interfaccia programmatica per raccogliere istantanee delle tendenze pubbliche attuali di X per WOEID numerico.

Invia uno o più identificatori di località noti come stringhe numeriche. L’endpoint non traduce il nome di una città o di un paese in un WOEID.

Ha 100 come valore predefinito, accetta interi da 20 a 2.000 e viene applicato separatamente a ogni WOEID. La fonte può esporre meno tendenze attuali del limite richiesto.

Un record contiene il nome della tendenza come id e text, una posizione di origine se presente, collected_at e campi extra per WOEID, query e descrizione quando disponibili.

No. Restituisce un’istantanea attuale per ogni WOEID richiesto; per creare uno storico pianifica e salva esecuzioni ripetute nel tuo sistema.

I record salvati vengono deduplicati per nome di tendenza normalizzato all’interno di un’attività. Se lo stesso nome compare in più località inviate, il primo record salvato può conservare un solo valore di extra.woeid.

Ogni tendenza normalizzata salvata correttamente costa 0,5 crediti SocQ. La stima usa results_limit per ogni WOEID inviato e i crediti prepagati non usati vengono rimborsati dopo la chiusura dell’attività.