Recuperare Post storici con l'endpoint di ricerca full-archive v2

​

Introduzione

Gli endpoint Search Posts nell’ambito della v2 consentono di ricevere Post relativi a temi di interesse, in base a una query di ricerca definita da te. Sono disponibili due endpoint con v2 Search Posts: la ricerca recente, accessibile a tutti gli sviluppatori con account approvato e in grado di cercare Post fino a sette giorni prima, e la ricerca su archivio completo, disponibile solo per i ricercatori approvati per il percorso di prodotto Academic Research, che consente di cercare nell’intero archivio di Post risalente a marzo 2006.

Puoi consultare l’intera offerta di ricerca nella pagina di panoramica della ricerca.

Questi endpoint Search Posts coprono uno dei casi d’uso più comuni per i ricercatori accademici, che possono utilizzarli per studi longitudinali o per analizzare un argomento o un evento passato.

Questo tutorial fornisce una guida passo-passo per i ricercatori che desiderano usare l’endpoint di ricerca su archivio completo per esplorare l’intera cronologia dei dati pubblici di X. Mostrerà inoltre diversi modi per creare un dataset, ad esempio recuperando Post con geotag, e come scorrere i Post disponibili per una query.

​

Prerequisiti

Attualmente, questo endpoint è disponibile solo all’interno del product track Academic Research. Per utilizzare questo endpoint, devi richiedere l’accesso. Scopri di più su procedura di candidatura e requisiti per questo track.

​

Collega un’App al Project accademico

Una volta approvato per utilizzare il prodotto Academic Research, vedrai il tuo Project accademico nel developer portal. Dalla sezione “Projects and Apps”, fai clic su “Add App” per collegare la tua X App al Project.

Quindi puoi scegliere un’App esistente e collegarla al tuo Project (come mostrato di seguito).

Oppure puoi creare una nuova App, assegnarle un nome e fare clic su “Complete”, per collegare una nuova App al tuo Project accademico.

Questo ti fornirà le tue API Key e il Bearer Token, che potrai poi utilizzare per connetterti all’endpoint di ricerca full-archive.

Nota bene

Le chiavi nello screenshot sopra sono oscurate, ma nel tuo developer portal potrai vedere i valori effettivi per API Key, API Secret Key e Bearer Token. Salva queste chiavi e il Bearer Token perché ti serviranno per effettuare chiamate all’endpoint di ricerca full-archive.

​

Connessione all’endpoint di ricerca su archivio completo

Il comando cURL seguente mostra come recuperare Post storici dall’account @XDevelopers. Sostituisci $BEARER_TOKEN con il tuo Bearer Token, incolla l’intera richiesta nel terminale e premi Invio.

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

Vedrai il JSON di risposta.

Per impostazione predefinita, verranno restituiti solo i 10 Post più recenti. Se desideri più di 10 Post per richiesta, puoi usare il parametro max_results e impostarlo su un massimo di 500 Post per richiesta, come mostrato di seguito:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Creazione di query

Come si può vedere negli esempi sopra, utilizzando il parametro query è possibile specificare i dati che si desidera cercare. Ad esempio, se si desidera recuperare tutti i Post che contengono la parola covid o la parola coronavirus, si può utilizzare l’operatore OR tra parentesi e la query può essere (covid OR coronavirus), e quindi la chiamata all’API sarà simile alla seguente:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Analogamente, se vuoi tutti i Post che contengono la parola covid19 e non sono Retweet, puoi usare l’operatore is:retweet con il NOT logico (rappresentato da -), quindi la tua query può essere covid19 -is:retweet e la tua chiamata API sarà:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Consulta questa guida per l’elenco completo degli operatori supportati nell’endpoint di ricerca dell’archivio completo.

​

Utilizzo dei parametri start_time ed end_time per ottenere Post storici

Quando si utilizza l’endpoint di ricerca full-archive, per impostazione predefinita vengono restituiti i Post degli ultimi 30 giorni. Se si desidera ottenere Post più vecchi di 30 giorni, è possibile utilizzare i parametri start_time ed end_time nella chiamata API. Questi parametri devono essere nel formato data-ora RFC3339 valido, ad esempio 2020-12-21T13:00:00.00Z. Pertanto, se si desidera ottenere tutti i Post dell’account XDevelopers per il mese di dicembre 2020, la chiamata API sarà:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Recupero di Post storici con geotag

I Post con geotag sono Post che hanno informazioni geografiche associate, come città, stato, paese, ecc.

​

Utilizzo dell’operatore has:geo

Se desideri recuperare Post che includono dati geografici, puoi utilizzare l’operatore has:geo. Ad esempio, la seguente richiesta cURL recupererà solo i Post dall’handle @XDevelopers che contengono dati geografici:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

Utilizzo dell’operatore place_country

Allo stesso modo, puoi limitare i Post che includono dati geospaziali a un determinato paese utilizzando l’operatore place_country. Il comando cURL seguente recupererà tutti i Post dell’handle @XDevelopers provenienti dagli Stati Uniti:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

Il paese è indicato sopra utilizzando il codice ISO alpha-2 a due lettere. I codici ISO validi sono disponibili qui.

​

Ottenere più di 500 Post storici utilizzando il next_token

Come indicato sopra, per impostazione predefinita puoi ottenere fino a 500 Post per richiesta per una query all’endpoint di ricerca dell’archivio completo. Se per la tua query sono disponibili più di 500 Post, la risposta JSON includerà un next_token che puoi aggiungere alla chiamata API per ottenere i Post successivi disponibili per quella query. Questo next_token è disponibile nell’oggetto meta della risposta JSON, che si presenta più o meno così:

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Pertanto, per ottenere i prossimi Post disponibili, usa il valore next_token presente in questo oggetto meta e impiegalo come valore di next_token nella tua chiamata API all’endpoint di ricerca dell’archivio completo, come mostrato di seguito (userai il tuo Bearer Token e il valore di Next Token ottenuto dalla tua chiamata API precedente).

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

In questo modo puoi continuare a verificare se è disponibile un next_token e, se non hai raggiunto il numero desiderato di Post da raccogliere, puoi continuare a chiamare l’ endpoint full-archive con il nuovo next_token per ogni richiesta. Tieni presente che l’endpoint di ricerca full-archive incide sul tuo totale Post cap, ovvero il numero di Post al mese che puoi ottenere dalla X API per Project. Quindi presta attenzione alla logica del tuo codice durante il paging dei risultati per essere certo di non finire involontariamente per esaurire il tuo Post cap.

Di seguito trovi alcune risorse utili quando utilizzi l’endpoint di ricerca full-archive. Ci farebbe piacere ricevere il tuo feedback. Contattaci su @XDevelopers o sui nostri community forums per domande su questo endpoint.

​

Risorse aggiuntive

• Riferimento API dell’endpoint di ricerca nell’archivio completo
• Nozioni di base per creare una query di ricerca