XTwitterScrapingTutorial sulle API

Come cercare e raccogliere i post di X/Twitter con un’API

Raccogli profili, post, timeline, ricerche, risposte e citazioni pubblici di X con endpoint asincroni e JSON normalizzato.

SocQAggiornato il 10 settembre 20269 min di lettura

Nel browser X sembra ancora una timeline. La specifica dei dati pubblici è più ristretta: un nome utente non è l’URL di un post, una citazione non è un repost, una risposta non è una citazione e un post eliminato o protetto deve fallire in modo pulito invece di diventare un record vuoto.

Questo tutorial costruisce un flusso di lavoro di produzione con le API di X di SocQ. Copre accesso ufficiale e pubblico, instradamento degli endpoint, pulizia degli input, attività asincrone, significato dei campi, cadenza di aggiornamento e uso responsabile.

Risposta rapida: invia nomi utente, URL di status di x.com o twitter.com, oppure una query di ricerca a POST /v1/x/{resource}, salva l’ID dell’attività e interroga /v1/tasks/{id}. Non unire citazioni, repost e risposte in un’unica tabella senza una colonna che distingua la risorsa.

API ufficiale di X o API di dati pubblici?

L’API ufficiale di X è a pagamento e basata su permessi. È il prodotto giusto quando devi pubblicare, inviare messaggi diretti, gestire gli annunci, seguire o mettere like come utente, oppure usare stream e altre superfici autorizzate dall’account. Accesso e prezzi cambiano; considera la documentazione per sviluppatori attuale come fonte di verità per i prodotti di scrittura e per i partner.

SocQ è un livello di lettura pubblica per profili supportati, post noti, finestre di post di un utente, ricerche, relazioni di conversazione e tendenze. Non si autentica come utente di X e non sostituisce la pubblicazione o gli annunci ufficiali. Per prezzi e inquadramento dei fornitori leggi alternative alle API di Twitter, API di scraping per Twitter e alternative a TwitterAPI.io. Scegli il modello di accesso prima di scegliere un endpoint.

Scegliere l’endpoint X corretto

RisorsaEndpointInput pubblico accettatoUso tipico
Profili/v1/x/profilesNomi utente, con o senza @Identità pubblica e conteggi visibili
Post/v1/x/postsURL di status di x.com o twitter.comUn singolo post noto
Post di un utente/v1/x/user-postsNomi utentePost pubblici recenti di un account
Ricerca/v1/x/searchQueryScoperta di post pubblici (latest o top)
Risposte/v1/x/post-repliesURL di statusRisposte a un post noto
Citazioni/v1/x/post-quotesURL di statusCitazioni di un post noto

Sono disponibili anche:

Citazioni, repost e risposte sono risorse diverse. Una citazione ha un proprio testo. Un elenco di retweeter è un insieme di profili. Una risposta è un post che appartiene a una conversazione. Non fare l’upsert come se fossero lo stesso oggetto.

Normalizzare nomi utente, URL e query

Conserva il valore inviato, poi pulisci una copia:

  1. Accetta nomi utente con o senza @, poi salva un unico nome utente canonico.
  2. Accetta sia gli host x.com sia twitter.com. Richiedi un percorso numerico /status/{id} per gli endpoint che lavorano su post.
  3. Elimina i parametri di query di tracciamento. Non richiedere un host mobile o di lingua specifico se l’ID dello status è integro.
  4. Deduplica i nomi utente senza distinguere maiuscole e minuscole e i post per ID dello status.
  5. Rifiuta query e nomi utente vuoti prima dell’invio.
  6. Conserva le espressioni di ricerca nella riga di provenienza, così chi analizza i dati può spiegare perché un post è entrato nel dataset.

user-posts e search accettano results_limit da 20 a 2.000 a passi di 20. Il sort_by della ricerca è latest o top. post-replies accetta anche sort_by con valore relevance, latest o likes.

Inviare un’attività di raccolta

Raccogliere profili:

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"]}'

Raccogliere post noti da uno dei due hostname:

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"]}'

Raccogliere una finestra di post di un utente:

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}'

Cercare post pubblici:

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"}'

Raccogliere risposte e citazioni come job separati:

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}'

Salva l’ID dell’attività restituito insieme al nome della risorsa e agli input canonici.

Interrogare lo stato dell’attività senza creare duplicati

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

Considera normali gli stati queued e running. Usa un backoff esponenziale. Quando l’attività ha successo, leggi data.results.items e segui next_cursor finché has_more è true.

Un worker robusto dovrebbe salvare in modo persistente:

  • ID del batch e ID dell’attività SocQ.
  • Risorsa e nomi utente, URL o query canonici.
  • Orari di invio e di completamento.
  • Stato finale e categoria dell’errore.
  • Ultimo cursore dei risultati elaborato.

Il riavvio di un worker non è un motivo per inviare di nuovo la stessa ricerca.

Capire i campi restituiti

I record condividono id, platform, resource, type, url, created_at, collected_at e extra.

Un profilo include username, name, description, avatar_url, cover_url, is_verified, is_private e metriche visibili. Gli account protetti non sono un obiettivo per i dati pubblici.

Un post include text, language, author, metriche visibili, media, hashtags e mentions quando sono pubblici. Usa id come chiave preferita dell’entità e l’URL dello status come provenienza.

Risposte e citazioni riutilizzano la struttura del post. I retweeter riutilizzano la struttura del profilo. Le tendenze sono righe di scoperta legate a una località, non post.

I post eliminati e privati devono fallire al confine dell’input o dell’attività. Non inserire un post vuoto, non inventare zeri di engagement e non riutilizzare collected_at come created_at.

I risultati di ricerca sono scoperta ordinata per rilevanza. latest e top sono ordinamenti diversi di una finestra delimitata, non un archivio storico completo.

Worker Python per profili, post e ricerca

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",
})

Prima di portarlo in produzione, aggiungi la paginazione a cursore, nuovi tentativi limitati per timeout e risposte 5xx ripetibili, e upsert idempotenti.

Modellare separatamente post e istantanee delle metriche

L’identità di un post e le sue metriche cambiano con velocità diverse.

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

Fai l’upsert per resource + id. Salva citazioni, risposte e post di origine nella stessa tabella dei post solo se resource resta una colonna obbligatoria. Tieni i retweeter in una tabella di profili o di relazioni.

Non calcolare la crescita delle citazioni da un’istantanea dei retweeter. Le metriche non sono intercambiabili.

Convalidare prima dell’archiviazione

  • platform deve essere uguale a x.
  • resource deve corrispondere all’endpoint.
  • Gli URL di status devono contenere un ID numerico /status/ quando la risorsa riguarda i post.
  • I nomi utente degli autori dovrebbero corrispondere all’account inviato quando la risorsa è user-posts e il campo è presente.
  • I conteggi devono essere numeri non negativi oppure null.
  • I timestamp devono essere interpretabili.
  • Un input privato o eliminato che è fallito non deve diventare un post vuoto riuscito.

Conserva le righe non valide in quarantena insieme al payload grezzo dell’attività.

Scegliere la pianificazione di aggiornamento per entità

EntitàCadenza iniziale sensataMotivo
ProfiloSettimanale o mensileBio e campi di identità cambiano lentamente
Post notoDa oraria a giornaliera finché è attivoLe metriche pubbliche si muovono rapidamente
Finestra di post di un utenteDa oraria a giornaliera per il monitoraggioLe timeline sono delimitate e ordinate per rilevanza
RicercaCon una pianificazione adatta alla querylatest e top non sono archivi
Risposte / citazioniOraria finché un post è attivoLe relazioni di conversazione arrivano a ondate
Follower / seguitiSettimanaleLe liste sono grandi e procedono a passi di 200
TendenzeOraria o alcune volte al giornoGli insiemi di WOEID ruotano

Riduci la raccolta quando la domanda di business non richiede un’istantanea più recente.

Problemi più comuni

L’URL di un post non restituisce nulla

Verifica che l’URL sia pubblico, ancora disponibile e contenga /status/{id}. I post eliminati e protetti devono fallire in modo pulito. Conserva l’errore a livello di input.

La ricerca sembra incompleta

results_limit pone un tetto alla richiesta. Ranking, indicizzazione e il passaggio tra latest e top cambiano la pagina. Salva query e ordinamento insieme ai record.

Le citazioni sono state salvate come repost

Sono endpoint diversi e oggetti diversi. Mantieni resource nella chiave primaria.

I job sui follower rifiutano il limite

Follower e seguiti accettano da 200 a 2.000 a incrementi di 200. User-posts e ricerca usano passi di 20.

Le metriche non coincidono con quelle del browser

I conteggi pubblici sono istantanee. Possono essere in ritardo, arrotondati o nascosti. Confronta collected_at prima di dare la colpa al parser.

Lo stesso utente compare due volte

Canonicalizza i nomi utente e preferisci un ID pubblico stabile. Mantieni una tabella di alias quando un account cambia nome.

Uso responsabile dei dati di X

Raccogli solo i campi pubblici necessari per uno scopo legittimo. Non aggirare account protetti, blocchi, muri di login o altri controlli di accesso. Evita la profilazione di singole persone su aspetti sensibili e le decisioni automatizzate che potrebbero incidere in modo significativo su una persona senza garanzie.

I dati di X possono essere dati personali. Stabilisci una base giuridica dove richiesto, definisci regole di conservazione ed eliminazione, proteggi le chiavi API e le esportazioni e verifica i termini attuali di X con una consulenza legale qualificata. Un’API di dati pubblici non concede una licenza per ripubblicare post o media.

Domande frequenti (FAQ)

Fare scraping di X o Twitter è legale?

Non esiste una risposta universale. Dipende da giurisdizione, dati, metodo, scopo, contratto e garanzie adottate. Questo tutorial non è una consulenza legale.

Questo sostituisce l’API ufficiale di X?

No. L’accesso ufficiale resta necessario per pubblicazione, messaggi diretti, annunci, stream e altre azioni basate su permessi. SocQ copre le letture pubbliche supportate.

Posso raccogliere post privati o eliminati?

No. Questi input devono fallire in modo pulito. Non aggirare la protezione.

Le citazioni sono uguali ai repost?

No. Le citazioni sono post. I retweeter sono profili. Le risposte sono una terza risorsa.

La ricerca restituisce una cronologia completa?

No. Restituisce una finestra delimitata e ordinata per una singola query.

Quale chiave devo usare per la deduplicazione?

Preferisci resource + id. Usa come alternativa di riserva un URL di status normalizzato o un nome utente quando l’ID pubblico manca.

X API

Prova il flusso di lavoro con un URL pubblico di X

Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.

Scopri le API di X