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.comotwitter.com, oppure una query di ricerca aPOST /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
| Risorsa | Endpoint | Input pubblico accettato | Uso tipico |
|---|---|---|---|
| Profili | /v1/x/profiles | Nomi utente, con o senza @ | Identità pubblica e conteggi visibili |
| Post | /v1/x/posts | URL di status di x.com o twitter.com | Un singolo post noto |
| Post di un utente | /v1/x/user-posts | Nomi utente | Post pubblici recenti di un account |
| Ricerca | /v1/x/search | Query | Scoperta di post pubblici (latest o top) |
| Risposte | /v1/x/post-replies | URL di status | Risposte a un post noto |
| Citazioni | /v1/x/post-quotes | URL di status | Citazioni di un post noto |
Sono disponibili anche:
post-retweetersper URL di status pubblici.followers-listefollowing-listper nomi utente, conresults_limitda 200 a 2.000 a passi di 200.trendsper WOEID numerici.
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:
- Accetta nomi utente con o senza
@, poi salva un unico nome utente canonico. - Accetta sia gli host
x.comsiatwitter.com. Richiedi un percorso numerico/status/{id}per gli endpoint che lavorano su post. - Elimina i parametri di query di tracciamento. Non richiedere un host mobile o di lingua specifico se l’ID dello status è integro.
- Deduplica i nomi utente senza distinguere maiuscole e minuscole e i post per ID dello status.
- Rifiuta query e nomi utente vuoti prima dell’invio.
- 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
platformdeve essere uguale ax.resourcedeve 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-postse 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 sensata | Motivo |
|---|---|---|
| Profilo | Settimanale o mensile | Bio e campi di identità cambiano lentamente |
| Post noto | Da oraria a giornaliera finché è attivo | Le metriche pubbliche si muovono rapidamente |
| Finestra di post di un utente | Da oraria a giornaliera per il monitoraggio | Le timeline sono delimitate e ordinate per rilevanza |
| Ricerca | Con una pianificazione adatta alla query | latest e top non sono archivi |
| Risposte / citazioni | Oraria finché un post è attivo | Le relazioni di conversazione arrivano a ondate |
| Follower / seguiti | Settimanale | Le liste sono grandi e procedono a passi di 200 |
| Tendenze | Oraria o alcune volte al giorno | Gli 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