Search API: Enterprise

Nota:

Abbiamo rilasciato una nuova versione della ricerca dei Post e del conteggio dei Post in X API v2. Ti invitiamo a scoprire le novità di X API v2.

Questi endpoint sono stati aggiornati per includere i metadata delle modifiche ai Post. Scopri di più su questi metadata nella pagina dei fondamenti “Modifica dei Post”. 

​

Panoramica

Enterprise

Le API Enterprise sono disponibili solo nei nostri livelli di accesso gestiti. Per utilizzare queste API, devi prima configurare un account con il nostro team vendite Enterprise. Per saperne di più, consulta QUI.

Puoi visualizzare tutte le offerte di ricerca dei Post della X API QUI.

Esistono due API di ricerca Enterprise:

1. La 30-Day Search API fornisce dati degli ultimi 30 giorni.
2. La Full-Archive Search API fornisce accesso completo e immediato all’intero corpus di dati di X, risalente fino al primo Post di marzo 2006.

Queste API RESTful supportano una singola query fino a 2.048 caratteri per richiesta. Le query sono scritte con la sintassi delle regole PowerTrack: vedi Regole e filtraggio per maggiori dettagli. Gli utenti possono specificare qualsiasi intervallo temporale, con granularità al minuto. Tuttavia, le risposte saranno limitate al minore tra il maxResults specificato oppure 31 giorni e includeranno un next token per la paginazione del set di risultati successivo. Se i parametri temporali non sono specificati, l’API restituirà i dati corrispondenti dei 30 giorni più recenti.

Le API di ricerca Enterprise forniscono accesso a bassa latenza, a piena fedeltà e basato su query all’archivio dei Post, con granularità al minuto. I dati dei Post sono forniti in ordine cronologico inverso, a partire dal Post più recente che corrisponde alla tua query. I Post sono disponibili dalla search API circa 30 secondi dopo la pubblicazione.

Questi endpoint di ricerca forniscono metadata di modifica dei Post. Tutti gli oggetti relativi ai Post creati dal 29 settembre 2022 includono metadata di modifica del Post, anche se il Post non è mai stato modificato. Ogni volta che un Post viene modificato, viene creato un nuovo ID del Post. La cronologia delle modifiche di un Post è documentata da un array di ID del Post, a partire dall’ID originale.

Questi endpoint restituiranno sempre la modifica più recente, insieme a qualsiasi cronologia delle modifiche. Qualsiasi Post raccolto dopo la sua finestra di modifica di 30 minuti rappresenterà la sua versione finale. Per saperne di più sui metadata di Edit Post, consulta la pagina Fondamenti di Edit Posts.

Le richieste includono un parametro maxResults che specifica il numero massimo di Post da restituire per risposta dell’API. Se alla query sono associati più Post rispetto a questo numero massimo per risposta, nella risposta è incluso un next token. Questi next token vengono utilizzati nelle richieste successive per scorrere l’intero set di Post associati alla query.

Queste API di ricerca Enterprise forniscono un endpoint counts che consente agli utenti di richiedere il volume di dati associato alla loro query. 

​

Tipi di richiesta

Le API di ricerca Enterprise supportano due tipi di richiesta:

​

Richieste di ricerca (data)

Le richieste alle API di ricerca Enterprise consentono di ottenere fino a 500 risultati per risposta in un determinato intervallo temporale, con la possibilità di utilizzare la paginazione per recuperare ulteriori data. Utilizzando il parametro maxResults, puoi specificare dimensioni di pagina più piccole per casi d’uso di visualizzazione (consentendo all’utente di richiedere più risultati secondo necessità) o dimensioni di pagina più grandi (fino a 500) per acquisizioni di data più estese. I data vengono restituiti in ordine cronologico inverso e sono conformi al momento della consegna.

​

Richieste di conteggio (Conteggio Post)

Le richieste di conteggio consentono di recuperare i conteggi dell’attività storica, che riflettono il numero di attività che corrispondono a una determinata query durante l’intervallo di tempo richiesto. La risposta fornirà sostanzialmente un istogramma dei conteggi, raggruppati per giorno, ora o minuto (il bucket predefinito è ora). È importante notare che i risultati dei conteggi non sempre riflettono gli eventi di compliance (ad es. eliminazioni di Post) che avvengono molto tempo dopo (oltre 7 giorni) la pubblicazione di un Post; pertanto, è previsto che la metrica dei conteggi possa non corrispondere sempre a quella di una richiesta di data per la stessa query.

Nota di fatturazione: ogni richiesta – incluse le richieste di paginazione – effettuata verso gli endpoint di data e di conteggi viene conteggiata come richiesta a pagamento. Pertanto, se sono presenti più pagine di risultati per una singola query, scorrere le X pagine di risultati equivarrà a X richieste ai fini della fatturazione.

​

Operatori disponibili

Le Enterprise Search API supportano regole fino a 2.048 caratteri e gli operatori elencati di seguito. Per descrizioni dettagliate, vedere QUI. 

Corrispondenza sul contenuto dei Post:	Corrispondenza sugli account di interesse:	Attributi del Post:	Operatori geospaziali:
* keyword * “quoted phrase” * “keyword1 keyword2”~N * # * @ * $ * url: * lang:	* from: * to: * retweets_of:	* is:retweet * has:mentions * has:hashtags * has:media * has:videos * has:images * has:links * has:symbols * is:verified * -is:nullcast (operatore solo di negazione)	* bounding_box:[west_long south_lat east_long north_lat] * point_radius:[lon lat radius] * has:geo * place: * place_country: * has:profile_geo * profile_country: * profile_region: * profile_locality:

Note: Non annidare/integrare operatori: “#cats” verrà interpretato come cats dalle Search API. L’operatore ‘lang:’ e tutti gli operatori ‘is:’ e ‘has:’ non possono essere usati da soli e devono essere combinati con un’altra clausola (ad es. @XDevelopers has:links).    

Le Search API utilizzano un set limitato di operatori a causa della tokenizzazione e delle modalità di corrispondenza. Le Enterprise real-time e le batched historical API forniscono operatori aggiuntivi. Vedere QUI per maggiori dettagli.

Per ulteriori dettagli, consultare la guida Introduzione agli operatori.

​

Disponibilità dei dati / date importanti

Quando si utilizza la Full-Archive search API, tenere presente che la piattaforma X ha continuato a evolversi dal 2006. Con l’aggiunta di nuove funzionalità, agli oggetti JSON sottostanti sono stati aggiunti nuovi metadati. Per questo motivo è importante capire quando sono stati aggiunti gli attributi dei Post su cui operano gli operatori di ricerca. Di seguito sono riportate alcune delle principali date di “nascita” di gruppi importanti di metadati. Per saperne di più su quando sono stati introdotti per la prima volta gli attributi dei Post, vedere questa guida.

• Primo Post: 21/3/2006
• Primi Retweet nativi: 6/11/2009
• Primo Post con geotag: 19/11/2009
• Prime URL indicizzate per il filtraggio: 27/8/2011
• Metadati avanzati per l’espansione delle URL (titoli e descrizioni dei siti web): 1/12/2014
• Metadati e filtri di arricchimento Profile Geo: 17/2/2015

​

Aggiornamenti dei dati e mutabilità

Con le Enterprise search API, alcuni dati all’interno di un Post sono mutabili, cioè possono essere aggiornati o modificati dopo l’archiviazione iniziale.

Questi dati mutabili rientrano in due categorie:

• Metadata dell’oggetto utente:
  • @handle dell’utente (l’id numerico non cambia mai)
  • Descrizione della bio
  • Conteggi: statuses, followers, friends, favorites, lists
  • Località del profilo
  • Altri dettagli come fuso orario e lingua
• Statistiche del Post, cioè tutto ciò che può essere modificato sulla piattaforma dalle azioni degli utenti (esempi sotto):
  • Numero di favorites
  • Numero di Retweet

Nella maggior parte di questi casi, le search API restituiscono i dati così come esistono sulla piattaforma al momento della query, piuttosto che al momento della generazione del Post. Tuttavia, nel caso di query che utilizzano operatori selettivi (ad es. from, to, @, is:verified), ciò potrebbe non essere così. I dati vengono aggiornati regolarmente nel nostro indice, con una frequenza maggiore per gli intervalli temporali più recenti. Di conseguenza, in alcuni casi i dati restituiti potrebbero non corrispondere esattamente a quelli attuali visualizzati su X.com, ma corrispondere a quelli presenti al momento dell’ultima indicizzazione.

Nota: questo problema di incoerenza si applica solo alle query in cui l’operatore si applica a dati mutabili. Un esempio è il filtraggio per nomi utente; la soluzione migliore è utilizzare gli id numerici degli utenti anziché gli @handle per queste query.

​

Richieste single-threaded vs. multi-threaded

Ogni cliente ha un limite di velocità definito per il proprio endpoint di ricerca. Il limite di velocità predefinito per minuto per la ricerca Full-Archive è di 120 richieste al minuto, per una media di 2 query al secondo (QPS). Questa media di QPS significa che, in teoria, è possibile effettuare 2 richieste all’API ogni secondo. Considerando la funzionalità di paginazione del prodotto, se una query di un anno ha un milione di Post associati, distribuiti uniformemente nell’arco dell’anno, sarebbero necessarie oltre 2.000 richieste (assumendo un ‘maxResults’ di 500) per ricevere tutti i data. Supponendo che servano due secondi per risposta, ciò equivale a 4.000 secondi (ovvero poco più di un’ora) per estrarre tutti quei data in modo seriale/sequenziale tramite un singolo thread (1 richiesta al secondo utilizzando il token “next” della risposta precedente). Non male!

Ora considera la situazione in cui vengono utilizzati dodici thread paralleli per ricevere i data. Supponendo una distribuzione uniforme del milione di Post sul periodo di un anno, potresti suddividere le richieste in dodici thread paralleli (multi-threaded) e sfruttare maggiormente il limite di velocità per secondo per il singolo “job”. In altre parole, potresti eseguire un thread per ciascun mese di interesse e, così facendo, i data potrebbero essere recuperati 12 volte più velocemente (ovvero ~6 minuti).

Questo esempio multi-threaded si applica altrettanto bene all’endpoint dei counts. Ad esempio, se volessi ricevere i conteggi dei Post per un periodo di due anni, potresti effettuare una richiesta single-threaded e scorrere a ritroso i counts 31 giorni alla volta. Supponendo che servano 2 secondi per risposta, occorrerebbero circa 48 secondi per effettuare le 24 richieste API e recuperare l’intero set di counts. Tuttavia, hai anche la possibilità di eseguire più richieste di un mese alla volta. Effettuando 12 richieste al secondo, l’intero set di counts potrebbe essere recuperato in circa 2 secondi.

​

Logica di retry

Se riscontri un errore 503 con le API di ricerca Enterprise, con ogni probabilità si tratta di un errore temporaneo che può essere risolto riprovando la richiesta dopo poco tempo.

Se la richiesta non va a buon fine per 4 volte di seguito e hai atteso almeno 10 minuti tra un errore e l’altro, procedi con i seguenti passaggi di troubleshooting:

• Riprova la richiesta dopo aver ridotto l’intervallo temporale coperto. Se necessario, ripeti fino ad arrivare a una finestra di 6 ore.
• Se stai utilizzando l’operatore OR con un numero elevato di termini, suddividili in regole separate e riprova ciascuna singolarmente.
• Se stai utilizzando un numero elevato di esclusioni nella regola, riduci i termini negati nella regola e riprova.

​

Avvio rapido

​

Introduzione a enterprise Search Posts: 30-Day API

L’enterprise Search Posts: 30-Day API fornisce Post pubblicati negli ultimi 30 giorni. I Post vengono individuati e restituiti in base alla query specificata nella tua richiesta. Una query è una regola con cui definisci cosa dovrebbe contenere il Post restituito. In questo tutorial cercheremo Post provenienti dall’account X @XDevelopers in lingua inglese.

I Post che ricevi nel payload possono essere in formato data, che ti fornisce l’intero payload del Post, oppure in formato counts, che ti restituisce dati numerici sul conteggio dei Post corrispondenti. Useremo cURL per effettuare richieste agli endpoint data e counts.

Ti serviranno:

• [Un account enterprise]https://developer.x.com/en/products/x-api/enterprise
• Il tuo nome utente, la password e il nome dell’account
• L’etichetta associata al tuo endpoint di ricerca, come visualizzata su console.gnip.com

​

Accesso all’endpoint data

L’endpoint data fornisce il payload completo del Post per i Post corrispondenti. Utilizzeremo gli operatori from: e lang: per trovare Post provenienti da @XDevelopers in inglese. Per ulteriori operatori fai clic qui.

cURL

cURL è uno strumento da riga di comando per recuperare o inviare file utilizzando la sintassi degli URL.

Copia la seguente richiesta cURL nel terminale dopo aver aggiornato i seguenti valori:

• Username <USERNAME> ad es. [e-mail]

• Account name <ACCOUNT-NAME> ad es. john-doe

• Label <LABEL> ad es. prod

• fromDate e toDate ad es. "fromDate":"201811010000", "toDate":"201811122359"

Dopo l’invio della richiesta, ti verrà richiesto di inserire la password.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'

​

Payload di risposta del data endpoint

Il payload restituito dalla tua richiesta API sarà in formato JSON, come mostrato di seguito.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "La tua fonte ufficiale per notizie, aggiornamenti ed eventi della Piattaforma Twitter. Hai bisogno di assistenza tecnica? Visita https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "SVP Product presso @Tagboard. Ho lavorato su Data, business e prodotto @Klout e per @LithiumTech; membro del consiglio @BBI; consulente @Insightpool. Il peggior disegnatore di lavagne al mondo.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti in tempo reale e permettendo agli elettori di porre domande durante i dibattiti,\" -- @adamostrow, @TEGNA\nScopri di più: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter e Tagboard collaborano per portare i migliori contenuti elettorali alle testate giornalistiche con Tagboard…",
									"description": "Di Tyler Singletary, Head of Product, Tagboard"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​

Accesso all’endpoint counts

Con l’endpoint counts, recupereremo il numero di Post originati dall’account @XDevelopers in inglese, raggruppati per day.

cURL

cURL è uno strumento da riga di comando per scaricare o inviare file utilizzando la sintassi degli URL.

Copia la seguente richiesta cURL nel tuo terminale dopo aver aggiornato i seguenti valori:

• Username <USERNAME> es. [e-mail]

• Account name <ACCOUNT-NAME> es. john-doe

• Label <LABEL> es. prod

• fromDate e toDate es. "fromDate":"201811010000", "toDate":"201811122359"

Dopo l’invio della richiesta, ti verrà richiesto di inserire la password.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/30day/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

​

Payload di risposta dell’endpoint Counts

Il payload restituito dalla richiesta all’API sarà in formato JSON, come mostrato di seguito.

{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

Ottimo lavoro! Ora hai eseguito correttamente l’accesso all’API Enterprise Search Posts: 30-Day.

Articoli di riferimento

• Introduzione agli Oggetti Post
• Operatori di ricerca
• Oggetti Post e payload

​

Introduzione a Enterprise Search Posts: Full-Archive API

L’Enterprise Search Posts: Full-Archive API ti fornisce accesso ai Post a partire dal primo pubblicato nel 2006. I Post vengono individuati e restituiti in base alla query specificata nella tua richiesta. Una query è una regola con cui definisci cosa deve contenere il Post restituito. In questo tutorial cercheremo Post provenienti dall’account X @XDevelopers in lingua inglese.

I Post restituiti nel payload possono essere nel formato data, che include il payload completo del Post, oppure nel formato counts, che fornisce dati numerici sul conteggio dei Post corrispondenti. Utilizzeremo cURL per effettuare richieste agli endpoint data e counts.

Avrai bisogno di quanto segue:

• [Un account Enterprise]https://developer.x.com/en/products/x-api/enterprise
• Il tuo nome utente, la password e il nome dell’account
• L’etichetta associata al tuo endpoint di ricerca, come visualizzata su console.gnip.com

​

Accesso all’endpoint data

L’endpoint data fornirà il payload completo dei Post che corrispondono ai criteri. Useremo gli operatori from: e lang: per trovare Post provenienti da @XDevelopers in inglese. Per altri operatori fai clic qui.

• cURL
• Esempio cURL

cURL

cURL è uno strumento da riga di comando per recuperare o inviare file utilizzando la sintassi degli URL.

Copia la seguente richiesta cURL nel tuo terminale dopo aver aggiornato i seguenti valori:

• Username <USERNAME> p.es. [e-mail]

• Account name <ACCOUNT-NAME> p.es. john-doe

• Label <LABEL> p.es. prod

• fromDate e toDate p.es. "fromDate":"201802010000", "toDate":"201802282359"

Dopo l’invio della richiesta, ti verrà richiesto di inserire la password.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>.json" -d '{"query":"from:TwitterDev lang:en","maxResults":"500","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>"}'

Payload di risposta dell’endpoint Data

Il payload restituito dalla richiesta all’API è in formato JSON, come mostrato di seguito.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti…",
			"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
			"truncated": false,
			"in_reply_to_status_id": null,
			"in_reply_to_status_id_str": null,
			"in_reply_to_user_id": null,
			"in_reply_to_user_id_str": null,
			"in_reply_to_screen_name": null,
			"user": {
				"id": 2244994945,
				"id_str": "2244994945",
				"name": "Twitter Dev",
				"screen_name": "TwitterDev",
				"location": "Internet",
				"url": "https:\/\/developer.x.com\/",
				"description": "La tua fonte ufficiale per notizie, aggiornamenti ed eventi della Piattaforma Twitter. Hai bisogno di assistenza tecnica? Visita https:\/\/devcommunity.com\/ ⌨️ #TapIntoTwitter",
				"translator_type": "null",
				"protected": false,
				"verified": true,
				"followers_count": 503828,
				"friends_count": 1477,
				"listed_count": 1437,
				"favourites_count": 2199,
				"statuses_count": 3380,
				"created_at": "Sat Dec 14 04:35:55 +0000 2013",
				"utc_offset": null,
				"time_zone": null,
				"geo_enabled": true,
				"lang": "en",
				"contributors_enabled": false,
				"is_translator": false,
				"profile_background_color": "null",
				"profile_background_image_url": "null",
				"profile_background_image_url_https": "null",
				"profile_background_tile": null,
				"profile_link_color": "null",
				"profile_sidebar_border_color": "null",
				"profile_sidebar_fill_color": "null",
				"profile_text_color": "null",
				"profile_use_background_image": null,
				"profile_image_url": "null",
				"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/880136122604507136\/xHrnqf1T_normal.jpg",
				"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/2244994945\/1498675817",
				"default_profile": false,
				"default_profile_image": false,
				"following": null,
				"follow_request_sent": null,
				"notifications": null
			},
			"geo": null,
			"coordinates": null,
			"place": null,
			"contributors": null,
			"retweeted_status": {
				"created_at": "Tue Oct 30 21:30:25 +0000 2018",
				"id": 1057384253116289025,
				"id_str": "1057384253116289025",
				"text": "\"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti… https:\/\/t.co\/w46U5TRTzQ",
				"source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>",
				"truncated": true,
				"in_reply_to_status_id": null,
				"in_reply_to_status_id_str": null,
				"in_reply_to_user_id": null,
				"in_reply_to_user_id_str": null,
				"in_reply_to_screen_name": null,
				"user": {
					"id": 175187944,
					"id_str": "175187944",
					"name": "Tyler Singletary",
					"screen_name": "harmophone",
					"location": "San Francisco, CA",
					"url": "http:\/\/medium.com\/@harmophone",
					"description": "SVP Product presso @Tagboard. Ho lavorato su Data, business e prodotto @Klout e per @LithiumTech; membro del consiglio @BBI; consulente @Insightpool. Il peggior disegnatore di lavagne al mondo.",
					"translator_type": "null",
					"protected": false,
					"verified": false,
					"followers_count": 1982,
					"friends_count": 1877,
					"listed_count": 245,
					"favourites_count": 23743,
					"statuses_count": 12708,
					"created_at": "Thu Aug 05 22:59:29 +0000 2010",
					"utc_offset": null,
					"time_zone": null,
					"geo_enabled": false,
					"lang": "en",
					"contributors_enabled": false,
					"is_translator": false,
					"profile_background_color": "null",
					"profile_background_image_url": "null",
					"profile_background_image_url_https": "null",
					"profile_background_tile": null,
					"profile_link_color": "null",
					"profile_sidebar_border_color": "null",
					"profile_sidebar_fill_color": "null",
					"profile_text_color": "null",
					"profile_use_background_image": null,
					"profile_image_url": "null",
					"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/719985428632240128\/WYFHcK-m_normal.jpg",
					"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/175187944\/1398653841",
					"default_profile": false,
					"default_profile_image": false,
					"following": null,
					"follow_request_sent": null,
					"notifications": null
				},
				"geo": null,
				"coordinates": null,
				"place": null,
				"contributors": null,
				"is_quote_status": false,
				"extended_tweet": {
					"full_text": "\"L'innovativo crowdsourcing che la collaborazione Tagboard, Twitter e TEGNA rende possibile sta portando alla luce conversazioni localmente rilevanti in tempo reale e permettendo agli elettori di porre domande durante i dibattiti,\" -- @adamostrow, @TEGNA\nScopri di più: https:\/\/t.co\/ivAFtanfje",
					"display_text_range": [
						0,
						259
					],
					"entities": {
						"hashtags": [],
						"urls": [
							{
								"url": "https:\/\/t.co\/ivAFtanfje",
								"expanded_url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
								"display_url": "blog.tagboard.com\/twitter-and-ta…",
								"unwound": {
									"url": "https:\/\/blog.tagboard.com\/twitter-and-tagboard-collaborate-to-bring-best-election-content-to-news-outlets-with-tagboard-e85fc864bcf4",
									"status": 200,
									"title": "Twitter e Tagboard collaborano per portare i migliori contenuti elettorali alle testate giornalistiche con Tagboard…",
									"description": "Di Tyler Singletary, Head of Product, Tagboard"
								},
								"indices": [
									236,
									259
								]
							}
						],
						"user_mentions": [
							{
								"screen_name": "adamostrow",
								"name": "Adam Ostrow",
								"id": 5695942,
								"id_str": "5695942",
								"indices": [
									204,
									215
								]
							},
							{
								"screen_name": "TEGNA",
								"name": "TEGNA",
								"id": 34123003,
								"id_str": "34123003",
								"indices": [
									217,
									223
								]
							}
						],
						"symbols": []
					}
				},
				"quote_count": 0,
				"reply_count": 1,
				"retweet_count": 6,
				"favorite_count": 19,
				"entities": {
					"hashtags": [],
					"urls": [
						{
							"url": "https:\/\/t.co\/w46U5TRTzQ",
							"expanded_url": "https:\/\/twitter.com\/i\/web\/status\/1057384253116289025",
							"display_url": "twitter.com\/i\/web\/status\/1…",
							"indices": [
								117,
								140
							]
						}
					],
					"user_mentions": [],
					"symbols": []
				},
				"favorited": false,
				"retweeted": false,
				"possibly_sensitive": false,
				"filter_level": "low",
				"lang": "en"
			},
			"is_quote_status": false,
			"quote_count": 0,
			"reply_count": 0,
			"retweet_count": 0,
			"favorite_count": 0,
			"entities": {
				"hashtags": [],
				"urls": [],
				"user_mentions": [
					{
						"screen_name": "harmophone",
						"name": "Tyler Singletary",
						"id": 175187944,
						"id_str": "175187944",
						"indices": [
							3,
							14
						]
					}
				],
				"symbols": []
			},
			"favorited": false,
			"retweeted": false,
			"filter_level": "low",
			"lang": "en",
			"matching_rules": [
				{
					"tag": null
				}
			]
		}
	],
	"requestParameters": {
		"maxResults": 100,
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

​

Accesso all’endpoint counts

Con l’endpoint counts recupereremo il numero di Post in inglese pubblicati dall’account @XDevelopers, raggruppati per day.

cURL

cURL è uno strumento da riga di comando per ottenere o inviare file utilizzando la sintassi degli URL.

Copia la seguente richiesta cURL nel tuo terminale dopo aver aggiornato i seguenti valori:

• Username <USERNAME> ad es. [e-mail]

• Account name <ACCOUNT-NAME> ad es. john-doe

• Label <LABEL> ad es. prod

• fromDate e toDate ad es. "fromDate":"201802010000", "toDate":"201802282359"

Dopo l’invio della richiesta ti verrà richiesto di inserire la password.

curl -X POST -u<USERNAME> "https://gnip-api.x.com/search/fullarchive/accounts/<ACCOUNT-NAME>/<LABEL>/counts.json" -d '{"query":"from:TwitterDev lang:en","fromDate":"<yyyymmddhhmm>","toDate":"<yyyymmddhhmm>","bucket":"day"}'

​

Payload di risposta dell’endpoint Counts

Il payload restituito dalla richiesta alla tua API sarà in formato JSON, come mostrato di seguito.

{
	"results": [
		{
			"timePeriod": "201811010000",
			"count": 0
		},
		{
			"timePeriod": "201811020000",
			"count": 1
		},
		{
			"timePeriod": "201811030000",
			"count": 0
		},
		{
			"timePeriod": "201811040000",
			"count": 0
		},
		{
			"timePeriod": "201811050000",
			"count": 0
		}
	],
	"totalCount": 1,
	"requestParameters": {
		"bucket": "day",
		"fromDate": "201811010000",
		"toDate": "201811060000"
	}
}

Ottimo lavoro! Ora hai effettuato correttamente l’accesso all’API Enterprise Search Posts: Full-Archive.

Articoli correlati

• Introduzione agli Oggetti Post
• Operatori di ricerca
• Oggetti Post e payload

​

Guide

​

Creare query di ricerca

​

Operatori Enterprise

Di seguito è riportato l’elenco di tutti gli operatori supportati nelle API di ricerca Enterprise di X:

• API di ricerca Enterprise degli ultimi 30 giorni
• API di ricerca Enterprise dell’archivio completo

Per un confronto affiancato degli operatori disponibili per prodotto, vedere QUI.

Operatore	Descrizione
keyword	Trova corrispondenze con una parola chiave tokenizzata nel corpo o negli URL di un Post. Si tratta di una corrispondenza tokenizzata, il che significa che la stringa della parola chiave verrà confrontata con il testo tokenizzato del corpo del Post – la tokenizzazione si basa sui caratteri di punteggiatura, simboli e separatori del piano base Unicode. Ad esempio, un Post con il testo “I like coca-cola” verrebbe suddiviso nei seguenti token: I, like, coca, cola. Questi token verrebbero quindi confrontati con la stringa della parola chiave utilizzata nella regola. Per trovare corrispondenze con stringhe contenenti punteggiatura (ad esempio, coca-cola), simboli o caratteri separatori, è necessario utilizzare una corrispondenza esatta tra virgolette come descritto di seguito. Nota: Con l’API Search, i caratteri accentati e speciali vengono normalizzati in caratteri latini standard, il che può cambiare i significati nelle lingue straniere o restituire risultati inaspettati: Ad esempio, “músic” corrisponderà a “music” e viceversa. Ad esempio, frasi comuni come “Feliz Año Nuevo!” in spagnolo, verrebbero indicizzate come “Feliz Ano Nuevo”, il che cambia il significato della frase. Nota: Questo operatore trova corrispondenze sia negli URL che negli URL espansi all’interno di un Post.
emoji	Trova corrispondenze con un emoji nel corpo di un Post. Gli emoji sono una corrispondenza tokenizzata, il che significa che l’emoji verrà confrontato con il testo tokenizzato del corpo del Post – la tokenizzazione si basa sui caratteri di punteggiatura, simboli/emoji e separatori del piano base Unicode. Ad esempio, un Post con il testo “I like ” verrebbe suddiviso nei seguenti token: I, like, . Questi token verrebbero quindi confrontati con l’emoji utilizzato nella regola. Nota che se un emoji ha una variante, è necessario utilizzare le “virgolette” per aggiungerlo a una regola.
”corrispondenza frase esatta”	Trova corrispondenze con la frase tokenizzata e ordinata nel corpo o negli URL di un Post. Si tratta di una corrispondenza tokenizzata, il che significa che la stringa della parola chiave verrà confrontata con il testo tokenizzato del corpo del Post – la tokenizzazione si basa sui caratteri di punteggiatura, simboli e separatori del piano base Unicode. Nota: La punteggiatura non viene tokenizzata e viene invece trattata come spazio bianco. Ad esempio, “#hashtag” tra virgolette corrisponderà a “hashtag” ma non a #hashtag (utilizzare l’operatore hashtag # senza virgolette per trovare corrispondenze con gli hashtag effettivi). Ad esempio, “cashtag" tra virgolette corrisponderà a "cashtag" ma non a cashtag (utilizzare l’operatore cashtag $ senza virgolette per trovare corrispondenze con i cashtag effettivi). Ad esempio, “Love Snow” corrisponderà a “#love #snow” Ad esempio, “#Love #Snow” corrisponderà a “love snow” Nota: Questo operatore trova corrispondenze sia negli URL che negli URL espansi all’interno di un Post.
”keyword1 keyword2”~N	Comunemente chiamato operatore di prossimità, trova corrispondenze con un Post in cui le parole chiave non distano più di N token l’una dall’altra. Se le parole chiave sono nell’ordine opposto, non possono distare più di N-2 token l’una dall’altra. Può contenere qualsiasi numero di parole chiave tra virgolette. N non può essere maggiore di 6. Nota che questo operatore è disponibile solo nelle API di ricerca enterprise.
from:	Trova corrispondenze con qualsiasi Post di un utente specifico. Il valore deve essere l’ID numerico dell’account X dell’utente o il nome utente (escludendo il carattere @). Vedi QUI o QUI per i metodi per cercare gli ID numerici dell’account X.
to:	Trova corrispondenze con qualsiasi Post che è in risposta a un particolare utente. Il valore deve essere l’ID numerico dell’account dell’utente o il nome utente (escludendo il carattere @). Vedi QUI per i metodi per cercare gli ID numerici dell’account X.
url:	Esegue una corrispondenza tokenizzata (parola chiave/frase) sugli URL espansi di un Post (simile a url_contains). I token e le frasi contenenti punteggiatura o caratteri speciali dovrebbero essere racchiusi tra virgolette doppie. Ad esempio, url:“/developer”. Sebbene generalmente non raccomandato, se si desidera trovare corrispondenze con un protocollo specifico, racchiudere tra virgolette doppie: url:“https://developer.x.com”. Nota: Quando si utilizza PowerTrack o Historical PowerTrack, questo operatore trova corrispondenze negli URL contenuti nel Post originale di un Quote Post. Ad esempio, se la regola include url:“developer.x.com”, e un Post contiene quell’URL, qualsiasi Quote Tweet di quel Post sarà incluso nei risultati. Questo non è il caso quando si utilizza l’API Search.
#	Trova corrispondenze con qualsiasi Post con l’hashtag specificato. Questo operatore esegue una corrispondenza esatta, NON una corrispondenza tokenizzata, il che significa che la regola “2016” corrisponderà ai post con l’hashtag esatto “2016”, ma non a quelli con l’hashtag “2016election” Nota: l’operatore hashtag si basa sull’estrazione di entità di X per trovare corrispondenze con gli hashtag, piuttosto che estrarre l’hashtag dal corpo stesso. Vedi QUI per maggiori informazioni sugli attributi JSON delle entità X.
@	Trova corrispondenze con qualsiasi Post che menziona il nome utente specificato. L’operatore to: restituisce una corrispondenza di sottoinsieme dell’operatore @mention.
$	Trova corrispondenze con qualsiasi Post che contiene il ‘cashtag’ specificato (dove il carattere iniziale del token è il carattere ’$’). Nota che l’operatore cashtag si basa sull’estrazione di entità ‘symbols’ di X per trovare corrispondenze con i cashtag, piuttosto che cercare di estrarre il cashtag dal corpo stesso. Vedi QUI per maggiori informazioni sugli attributi JSON delle entità X. Nota che questo operatore è disponibile solo nelle API di ricerca enterprise.
retweets_of:	Alias disponibile: retweets_of_user: Trova corrispondenze con Post che sono retweet di un utente specificato. Accetta sia nomi utente che ID numerici dell’account X (NON ID di stato del Post). Vedi QUI per i metodi per cercare gli ID numerici dell’account X.
lang:	Trova corrispondenze con Post che sono stati classificati da X come appartenenti a una particolare lingua (se, e solo se, il post è stato classificato). È importante notare che ogni Post è attualmente classificato come appartenente a una sola lingua, quindi utilizzare l’operatore AND insieme a più lingue non produrrà risultati. Nota: se non è possibile effettuare alcuna classificazione linguistica, il risultato fornito è ‘und’ (per indefinito). L’elenco sottostante rappresenta le lingue attualmente supportate e il loro corrispondente identificatore di lingua BCP 47:

Amarico: am	Tedesco: de	Malayalam: ml	Slovacco: sk
Arabo: ar	Greco: el	Maldiviano: dv	Sloveno: sl
Armeno: hy	Gujarati: gu	Marathi: mr	Curdo sorani: ckb
Basco: eu	Creolo haitiano: ht	Nepalese: ne	Spagnolo: es
Bengalese: bn	Ebraico: iw	Norvegese: no	Svedese: sv
Bosniaco: bs	Hindi: hi	Odia: or	Tagalog: tl
Bulgaro: bg	Hindi latinizzato: hi-Latn	Panjabi: pa	Tamil: ta
Birmano: my	Ungherese: hu	Pashto: ps	Telugu: te
Croato: hr	Islandese: is	Persiano: fa	Thai: th
Catalano: ca	Indonesiano: in	Polacco: pl	Tibetano: bo
Ceco: cs	Italiano: it	Portoghese: pt	Cinese tradizionale: zh-TW
Danese: da	Giapponese: ja	Rumeno: ro	Turco: tr
Olandese: nl	Kannada: kn	Russo: ru	Ucraino: uk
Inglese: en	Khmer: km	Serbo: sr	Urdu: ur
Estone: et	Coreano: ko	Cinese semplificato: zh-CN	Uiguro: ug
Finlandese: fi	Lao: lo	Sindhi: sd	Vietnamita: vi
Francese: fr	Lettone: lv	Singalese: si	Gallese: cy
Georgiano: ka	Lituano: lt

place:	Corrisponde ai Post contrassegnati con la località specificata o con l’X place ID (vedi esempi). I nomi di località composti da più parole (“New York City”, “Palo Alto”) devono essere racchiusi tra virgolette. Nota: consulta l’endpoint pubblico dell’API GET geo/search per informazioni su come ottenere gli X place ID. Nota: Questo operatore non produce corrispondenze sui Retweet, poiché i luoghi dei Retweet sono associati al Post originale. Non produce corrispondenze neanche per i luoghi associati al Post originale di un Quote Tweet.
place_country:	Corrisponde ai Post in cui il codice paese associato a un place taggato corrisponde al codice ISO alpha‑2 fornito. I codici ISO validi sono disponibili qui: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Nota: Questo operatore non produce corrispondenze sui Retweet, poiché i luoghi dei Retweet sono associati al Post originale. Non produce corrispondenze neanche per i luoghi associati al Post originale di un Quote Tweet.
point_radius:[lon lat radius]	Corrisponde alla posizione esatta (x,y) del Post quando presente e, in X, a un poligono geografico “Place”, laddove il Place sia completamente contenuto entro la regione definita. * Le unità di raggio supportate sono miglia (mi) e chilometri (km). * Il raggio deve essere inferiore a 25 mi. * La longitudine è nell’intervallo ±180 * La latitudine è nell’intervallo ±90 * Tutte le coordinate sono in gradi decimali. * Gli argomenti della regola sono racchiusi tra parentesi e separati da spazi. Nota: Questo operatore non produce corrispondenze sui Retweet, poiché i luoghi dei Retweet sono associati al Post originale. Non produce corrispondenze neanche per i luoghi associati al Post originale di un Quote Tweet.
bounding_box:[west_long south_lat east_long north_lat]	Alias disponibile: geo_bounding_box: Corrisponde alla posizione esatta (long, lat) del Post quando presente e, in X, a un poligono geografico “Place”, laddove il Place sia completamente contenuto entro la regione definita. * west_long e south_lat rappresentano l’angolo sud‑ovest del bounding box, dove west_long è la longitudine di quel punto e south_lat è la latitudine. * east_long e north_lat rappresentano l’angolo nord‑est del bounding box, dove east_long è la longitudine di quel punto e north_lat è la latitudine. * La larghezza e l’altezza del bounding box devono essere inferiori a 25 mi * La longitudine è nell’intervallo ±180 * La latitudine è nell’intervallo ±90 * Tutte le coordinate sono in gradi decimali. * Gli argomenti della regola sono racchiusi tra parentesi e separati da spazi. Nota: Questo operatore non produce corrispondenze sui Retweet, poiché i luoghi dei Retweet sono associati al Post originale. Non produce corrispondenze neanche per i luoghi associati al Post originale di un Quote Tweet.
profile_country:	Corrispondenza esatta sul campo “countryCode” dell’oggetto “address” nell’arricchimento Profile Geo. Utilizza un set normalizzato di codici paese a due lettere, basato sulla specifica ISO‑3166‑1‑alpha‑2. Questo operatore è fornito in luogo di un operatore per il campo “country” dell’oggetto “address” per maggiore concisione.
profile_region:	Corrisponde al campo “region” dell’oggetto “address” nell’arricchimento Profile Geo. Si tratta di una corrispondenza esatta dell’intera stringa. Non è necessario eseguire l’escape dei caratteri con una barra rovesciata. Ad esempio, se si effettua una corrispondenza con uno slash, usare “one/two”, non “one/two”. Usare virgolette doppie per far corrispondere sottostringhe che contengono spazi o punteggiatura.
profile_locality:	Corrisponde al campo “locality” dell’oggetto “address” nell’arricchimento Profile Geo. Si tratta di una corrispondenza esatta dell’intera stringa. Non è necessario eseguire l’escape dei caratteri con una barra rovesciata. Ad esempio, se si effettua una corrispondenza con uno slash, usare “one/two”, non “one/two”. Usare virgolette doppie per far corrispondere sottostringhe che contengono spazi o punteggiatura.

NOTA: Gli operatori is: e has: non possono essere usati da soli con la Search API e devono essere combinati con un’altra clausola.

Per esempio: @XDeevelopers has:links

has:geo	Trova corrispondenze con i Post che contengono dati di geolocalizzazione specifici forniti da X. Questi possono essere coordinate “geo” latitudine-longitudine, oppure una “location” sotto forma di “Place” di X, con nome visualizzato corrispondente, poligono geografico e altri campi. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:profile_geo	Alias disponibile: has:derived_user_geo Trova corrispondenze con i Post che contengono metadata Profile Geo, indipendentemente dal valore effettivo. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:links	Questo operatore trova corrispondenze con i Post che contengono link nel corpo del messaggio. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
is:retweet	Restituisce solo i retweet espliciti che corrispondono a una regola. Può anche essere negato per escludere i retweet che corrispondono a una regola e restituire solo il contenuto originale. Questo operatore cerca solo i veri Retweet, che utilizzano la funzionalità di retweet di X. I Tweet citati e i Post modificati che non utilizzano la funzionalità di retweet di X non verranno trovati da questo operatore. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
is:reply	Un operatore per filtrare i Post in base al fatto che siano o meno risposte ad altri Post. Restituisce solo le risposte esplicite che corrispondono a una regola. Può anche essere negato per escludere le risposte che corrispondono a una regola. Si noti che questo operatore è disponibile per la ricerca premium e enterprise a pagamento e non è disponibile negli ambienti di sviluppo Sandbox. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
is:quote	Restituisce solo i Quote Tweet, ovvero Post che fanno riferimento a un altro Post, come identificato da “is_quote_status”:true nei payload dei Post. Può anche essere negato per escludere i Quote Tweet. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
is:verified	Restituisce solo i Post il cui autore è “verificato” da X. Può anche essere negato per escludere i Post il cui autore è verificato. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:mentions	Trova corrispondenze con i Post che menzionano un altro utente X. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:hashtags	Trova corrispondenze con i Post che contengono un hashtag. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:media	Alias disponibile: has:media_link Trova corrispondenze con i Post che contengono un URL media classificato da X. Ad esempio, pic.x.com. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:images	Trova corrispondenze con i Post che contengono un URL media classificato da X. Ad esempio, pic.x.com. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:videos	Alias disponibile: has:video_link Trova corrispondenze con i Post che contengono video nativi di X, caricati direttamente su X. Questo non troverà corrispondenze con video creati con Vine, Periscope, o Post con link ad altri siti di hosting video. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.
has:symbols	Trova corrispondenze con i Post che contengono un simbolo cashtag (con un carattere ‘' iniziale. Ad esempio, tag). Si noti che questo operatore è disponibile solo nelle API di ricerca enterprise. Nota: Quando si utilizza l’API Search, questo operatore deve essere utilizzato in combinazione con altri operatori che non includono is: o has:.

​

Panoramica del prodotto

Il Full-archive Search di livello Enterprise è stato lanciato nell’agosto 2015, mentre la versione di livello premium è stata lanciata nel febbraio 2018. Questi prodotti di ricerca consentono ai clienti di accedere immediatamente a qualsiasi Post disponibile pubblicamente. Con Full-archive Search invii una singola query e ricevi una risposta nel classico stile RESTful. Full-archive Search implementa una paginazione fino a 500 Post per risposta e supporta un rate limit fino a 60 richieste al minuto (rpm) per il livello premium e 120 rpm per quello enterprise. Considerati questi dettagli, Full-archive Search può essere utilizzato per recuperare rapidamente Post e su larga scala, utilizzando richieste concorrenti.

A differenza di Historical PowerTrack, il cui archivio si basa su un set di flat file di Post su disco, l’archivio di Post di Full-archive Search è molto simile a un database online. Come per tutti i database, supporta l’esecuzione di query sui propri contenuti. Fa inoltre uso di un indice per consentire il recupero dei dati ad alte prestazioni. Con gli endpoint di Full-archive Search, il linguaggio di query è composto dai PowerTrack Operators e ciascuno di questi Operator corrisponde a un attributo JSON del Post indicizzato.

Inoltre, come Historical PowerTrack, sono presenti attributi del Post che sono aggiornati al momento in cui viene eseguita una query. Ad esempio, se oggi stai utilizzando la Search API per accedere a un Post pubblicato nel 2010, la descrizione del profilo dell’utente, la posizione “home” dell’account, il nome visualizzato e le metriche del Post per i conteggi di Favorites e Retweet saranno aggiornati ai valori odierni e non a quelli del 2010. 

​

Cronologie dei metadati

Di seguito è riportata una cronologia di quando gli operator dell’endpoint Full-archive search hanno iniziato a effettuare il matching. In alcuni casi il matching degli operator è iniziato ben dopo che una “convenzione di comunicazione” era diventata comune su X. Ad esempio, le @Replies sono emerse come convenzione degli utenti nel 2006, ma non sono diventate un oggetto di prima classe o un evento con JSON “di supporto” fino all’inizio del 2007. Di conseguenza, il matching sulle @Replies nel 2006 richiede un esame del corpo del Post, invece di fare affidamento sugli operator PowerTrack to: e in_reply_to_status_id:.

I dettagli forniti qui sono stati generati utilizzando Full-Archive Search (risultato di centinaia di ricerche). Questa cronologia non è completa o precisa al 100%. Se individui un’altra “data di nascita” di filtraggio/metadati fondamentale per il tuo caso d’uso, faccelo sapere.

Nota che l’indice di Search sottostante può essere ricostruito. Di conseguenza, questi dettagli cronologici sono soggetti a modifiche.

​

2006

• 26 marzo - lang:. Un esempio di metadata del Post reintegrato durante la generazione dell’indice di ricerca.
• 13 luglio - has:mentions inizia a dare corrispondenze.
• 6 ottobre - has:symbols. I $cashtag (o simboli) usati per discutere i simboli azionari diventano comuni solo all’inizio del 2009. Fino ad allora, la maggior parte degli utilizzi era probabilmente gergale (ad es.,$slang).
• 26 ottobre - has:links inizia a dare corrispondenze.
• 23 novembre - has:hashtags inizia a dare corrispondenze.

​

2007

• 30 gennaio - Prima @reply di prima classe (in_reply_to_user_id), reply_to_status_id: inizia a effettuare corrispondenze.
• 23 agosto - Gli hashtag emergono come convenzione comune per organizzare argomenti e conversazioni. Primo utilizzo reale una settimana dopo.

​

2009

• 15 maggio - is:retweet. Nota: questo operatore inizia a produrre corrispondenze con il rilascio “beta” dei Retweet ufficiali e il relativo pattern “Via @”. Durante questo periodo beta, il verbo Post è “post” e il Post originale non è incluso nel payload.
• 13 agosto - Viene rilasciata la versione finale dei Retweet ufficiali con il pattern “RT @”, un verbo impostato su “share” e l’attributo “retweet_status” contenente il Post originale (raddoppiando così approssimativamente le dimensioni del payload JSON).

​

2010

• 6 marzo - Gli operatori geografici has:geo, bounding_box: e point_radius: iniziano a restituire corrispondenze.
• 28 agosto - has:videos (Fino a febbraio 2015, questo operatore restituisce corrispondenze per i Post con link a specifici siti di hosting video come youtube.com, vimeo.com e vivo.com).

​

2011

• 20 luglio - has:media e has:images iniziano a essere applicati. Le foto native sono state annunciate ufficialmente il 9 agosto 2010.

​

2014

• 3 dicembre - (Circa) Alcuni metadata URL avanzati con title e description HTML iniziano a comparire nei payload. I metadata avanzati si sono affermati più pienamente nel maggio 2016.

​

2015

• 10 febbraio - has:videos corrisponde ai video “nativi” di X.
• 17 febbraio - Gli operatori Profile Geo has:profile_geo, profile_country:, profile_region:, profile_locality: iniziano a restituire corrispondenze.
• 17 febbraio - Gli operatori geografici per i Post place_country: e place: iniziano a restituire corrispondenze.

​

2016

• 1 maggio - Metadata degli URL migliorati resi più ampiamente disponibili e annunciati ufficialmente come parte del lancio di Gnip 2.0 nell’agosto 2016. Nessun operatore associato per questi metadata con le API di ricerca.

​

2017

• 22 febbraio - Le metadata dei sondaggi diventano disponibili in formato nativo avanzato. Nessun Operatore associato per queste metadata.

​

2022

• 27 settembre - Tutti gli Oggetti Post creati a partire da questa data dispongono dei metadati di Post modificato. Tutti gli endpoint Enterprise che forniscono Oggetti Post sono stati aggiornati per includere questi metadati a partire da questa data. I metadati di modifica forniti includono gli oggetti edit_history ed edit_controls. Questi metadati non verranno restituiti per i Post creati prima del 27 settembre 2022. Al momento non sono disponibili operator Enterprise che corrispondano a questi metadati. Per ulteriori informazioni sui metadati di Post modificato, consulta la pagina Edit Posts fundamentals.

​

2022

• 29 settembre - Tutti gli Oggetti Post creati a partire da questa data hanno a disposizione la metadata di Post modificato. Tutti gli endpoint Enterprise che forniscono Oggetti Post sono stati aggiornati per includere questa metadata a partire da questa data. La metadata di modifica fornita include gli oggetti edit_history ed edit_controls. Queste metadata non verranno restituite per i Post creati prima del 27 settembre 2022. Al momento non sono disponibili Enterprise Operators corrispondenti a questa metadata. Per saperne di più sulla metadata di Post modificato, consulta la pagina Edit Posts fundamentals.

​

Suggerimenti per il filtraggio

Considerate tutte le informazioni sulla timeline riportate sopra, è chiaro che ci sono molti dettagli da tenere a mente quando si scrivono i filtri delle API di Search. Ci sono due aspetti chiave da considerare:

• Alcuni metadata hanno date di “nascita”, quindi i filtri possono produrre falsi negativi. Tali ricerche includono operator che dipendono da metadata che non esistevano per tutto o parte del periodo di ricerca. Ad esempio, se cercate Post con l’operatore has:images, non otterrete corrispondenze per periodi antecedenti a luglio 2011. Questo perché quell’operatore corrisponde a foto native (allegate a un Post tramite l’interfaccia utente di X). Per un set di data più completo di Post di condivisione foto, i filtri per periodi precedenti a luglio 2011 dovrebbero includere clausole di regola che corrispondono a URL comuni per l’hosting di foto.
• Alcuni metadata sono stati integrati a posteriori con metadata provenienti da un periodo successivo alla pubblicazione su X.

Esistono diversi tipi di attributi su cui ci si concentra comunemente quando si creano query PowerTrack:

• Profili X
• Post originali o condivisi
• Classificazione della lingua del Post
• Post con georeferenziazione
• Media dei link condivisi

Alcuni di questi presentano comportamenti specifici del prodotto, mentre altri hanno comportamenti identici. Vedere di seguito per maggiori dettagli.

​

Profili X

Le API di Search restituiscono Post storici con i dati del profilo utente così come sono al momento del recupero. Se richiedi un Post del 2014, i metadati del profilo dell’utente rifletteranno lo stato al momento della query.

​

Post originali e Retweet

L’operatore PowerTrack _is:retweet_ consente di includere o escludere i Retweet. Chi utilizza questo operatore deve adottare due strategie per la corrispondenza dei Retweet (o per escluderla) con riferimento ai dati antecedenti ad agosto 2009. Prima di agosto 2009, è necessario verificare il messaggio del Post stesso, utilizzando la corrispondenza di frase esatta, per individuare il pattern “@RT ” (in realtà, se si filtrano i Retweet tra maggio e agosto 2009, andrebbe incluso anche il pattern “Via @”). Per i periodi successivi ad agosto 2009, è disponibile l’operatore is:retweet.

​

Classificazioni della lingua dei Post

Per filtrare in base alla classificazione della lingua di un Post, i prodotti storici di X differiscono notevolmente. Quando è stato creato l’archivio Search, a tutti i Post è stata retroattivamente applicata la classificazione della lingua di X. Pertanto, l’operatore lang: è disponibile per l’intero archivio dei Post.

​

Geo-referenziazione dei Post

Esistono tre modi principali per geo-referenziare i Post:

• Riferimenti geografici nel contenuto del Post. Il matching basato su riferimenti geografici nel contenuto del Post, sebbene spesso il metodo più impegnativo poiché dipende dalla conoscenza locale, è un’opzione applicabile all’intero archivio di Post. Qui c’è un esempio di match geo-referenziato del 2006 per l’area di San Francisco basato su un filtro “golden gate”.

• Post geo-taggati dall’utente. Con le API di ricerca la possibilità di iniziare a fare matching sui Post con alcuni Geo Operators è iniziata a marzo 2010, e con altri a febbraio 2015:

  • 6 marzo 2010: has:geo, bounding_box: e point_radius:
  • 17 febbraio 2015: place_country: e place:

• Posizione “home” del profilo dell’account impostata dall’utente. I Profile Geo Operators sono disponibili sia in Historical PowerTrack sia nelle API di ricerca. Con le API di ricerca, questi metadata Profile Geo sono disponibili a partire da febbraio 2015. Per i Post pubblicati prima che i metadata Profile Geo diventassero disponibili, è disponibile l’Operator bio_location: che può essere utilizzato per fare matching su input utente non normalizzati.

​

Link e media condivisi

Nel marzo 2012 è stato introdotto l’arricchimento degli URL espansi. Prima di allora, i payload dei Post includevano solo l’URL fornito dall’utente. Quindi, se l’utente includeva un URL abbreviato, poteva risultare difficile eseguire il matching sugli URL (espansi) di interesse. Con le Search API, questi metadata sono disponibili a partire da marzo 2012.

Nel luglio 2016 è stato introdotto l’arricchimento degli URL avanzati. Questa versione avanzata fornisce il titolo e la descrizione HTML di un sito web nel payload del Post, insieme agli Operator per eseguire il matching su tali elementi. Questi metadata iniziano a comparire nel dicembre 2014.

Nel settembre 2016 X ha introdotto gli “allegati nativi”, in cui un link condiviso finale non viene conteggiato nel limite di 140 caratteri del Post. Entrambi gli arricchimenti degli URL si applicano ancora a questi link condivisi.

Di seguito quando gli Search Operator correlati iniziano a effettuare il matching:

• 26 ottobre 2006 - has:links
• 20 luglio 2011 - has:images e has:media
• agosto 2011 - url: con l’Expanded URLs enrichment Già da settembre 2006 (url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube) corrisponde a http://x.com/Adam/statuses/16602, anche se non ci sono metadata urls[] in twitter_entities e negli oggetti gnip. “youtube.com” è un esempio di contenuto del messaggio che, senza alcun metadata urls[], corrisponde a url:youtube.
• 10 febbraio 2015 - has:videos per i video nativi. Tra il 28/08/2010 e il 10/02/2015, questo Operator effettua il matching dei Post con link a selezionati siti di hosting video come youtube.com, vimeo.com e vivo.com.
• 1º maggio 2016 - url_title: e url_description:, basati sull’Enhanced URLs enrichment, generalmente disponibili. I primi metadata Enhanced URL hanno iniziato ad apparire nel dicembre 2014.

​

Domande frequenti (FAQ)

​

Domande generali sull’API di ricerca dei Post

Il numero di Post che ricevo con l’endpoint data non corrisponde al numero di Post identificati dall’endpoint counts. Perché accade?

Esiste una differenza nota tra i risultati forniti dall’endpoint dei conteggi e quelli forniti dall’endpoint dei data. Potresti riscontrare una discrepanza nei risultati perché l’endpoint dei conteggi è pre‑compliance (cioè non considera elementi come Post eliminati, scrub geo, ecc.), mentre l’endpoint dei data è conforme al momento della consegna e tiene conto di tutti gli eventi di compliance.

Non ho ricevuto un Post che dovrebbe corrispondere alla mia query. Perché?

Ci sono diversi motivi per cui questo potrebbe essere successo, tra cui:

1. il Post che ti aspettavi di vedere proviene da un account protetto
2. l’endpoint data tiene conto di tutti gli eventi di compliance (il che significa che i Post eliminati, le geolocalizzazioni rimosse, ecc. non saranno inclusi nella risposta).

La mia query ha corrisposto a un Post ma include una keyword che avevo negato. Perché sta succedendo?

Questo è probabilmente dovuto a un uso scorretto delle nostre regole premium e del filtraggio. Consulta la nostra documentazione qui e assicurati di comprendere le restrizioni relative alla creazione delle regole.

Esistono librerie che posso utilizzare per iniziare a usare le API di Search Post?

Sì, ad esempio:

• Tweepy - utile per usare il prodotto standard di ricerca/Post (Python)
• X API - utile per usare le API standard di Search Post (Python)
• Search Posts Python e Search Posts Ruby - due ottimi strumenti utilizzabili con le API di Search Post Enterprise (e v2!)

Tutte le librerie che supportiamo direttamente sono disponibili sulla nostra pagina GitHub xdevplatform: https://github.com/xdevplatform.

Esistono altre librerie di terze parti che potrebbero essere utili; tuttavia, tieni presente che alcune potrebbero non funzionare con i nostri prodotti Premium ed Enterprise.

Riceverò mai un volume di Post inferiore al valore che imposto come `maxResults` nella mia richiesta all’endpoint dei dati?

Sì. Il nostro endpoint data applica la paginazione in base al maxResults specificato oppure dopo 30 giorni.

Ad esempio, se in un periodo di 30 giorni hai 800 Post, dovrai effettuare due richieste per ottenere tutti i risultati, perché il numero massimo di Post restituibili per richiesta è 500 (maxResults). E se nel primo mese hai solo 400 Post e nel secondo mese 100 Post, dovrai comunque effettuare due richieste per ottenere tutti i risultati, perché la paginazione avviene dopo un periodo di 30 giorni anche se la prima richiesta restituisce meno Post del maxResults specificato.

In quale ordine vengono restituite le Post corrispondenti?

I Post vengono restituiti in ordine cronologico inverso. Ad esempio, la prima pagina dei risultati mostrerà i Post più recenti che corrispondono alla query; la paginazione proseguirà finché le date di pubblicazione dei risultati non raggiungeranno il fromDate richiesto inizialmente.

In che modo le funzionalità di modifica dei Post influiscono sull’utilizzo e sulla fatturazione?

Solo il Post originale sarà conteggiato ai fini della fatturazione. Eventuali modifiche successive saranno ignorate e non contribuiranno al conteggio complessivo dell’attività.

Enterprise

Sono interessato a saperne di più sui prezzi della Enterprise Search Post API e a candidarmi per questa offerta. Come posso procedere?

Le nostre soluzioni Enterprise sono personalizzate, con prezzi prevedibili, per soddisfare le esigenze della tua azienda. Per ulteriori informazioni, invia la tua candidatura qui.

Come posso creare un set di regole che corrisponda al mio caso d’uso?

• Consulta la documentazione delle API di Search Post per Enterprise qui
• Informazioni utili su regole e filtraggio sono disponibili qui
• Informazioni utili sull’uso dell’endpoint data sono disponibili qui
• Informazioni utili sull’uso dell’endpoint counts sono disponibili qui
• Un elenco degli operatori disponibili è consultabile qui

Ho superato i limiti/cap mensili di richieste, ma ho bisogno di accedere a più data: cosa posso fare?

Per favore, mettiti in contatto con il tuo Account Manager di X, che potrà aiutarti in merito.

​

Guida alla risoluzione degli errori

Codice 404 - Non trovato

1. Assicurati di utilizzare i parametri corretti per ogni endpoint (ad es. il campo buckets può essere usato solo con l’endpoint counts, non con l’endpoint data)
2. Verifica attentamente che i campi :product, :account_name e :label siano corretti. Puoi trovare il valore di :label nella GNIP Console (solo clienti Enterprise).

​

Riferimenti API

​

API di ricerca Enterprise

Esistono due API di ricerca Enterprise:

• 30-Day Search API - fornisce Tweet pubblicati negli ultimi 30 giorni.
• Full-Archive Search API - fornisce Tweet a partire dal 2006, a cominciare dal primo Tweet pubblicato nel marzo 2006.

Queste API di ricerca condividono un’architettura comune e la documentazione riportata di seguito si applica a entrambe. Nota che per i Tweet creati a partire dal 29 settembre 2022, gli oggetti Tweet includono metadati di modifica che descrivono la relativa cronologia delle modifiche. Consulta la pagina dei fondamenti “Edit Tweets” per ulteriori dettagli.

Di seguito trovi dettagli importanti necessari per l’integrazione con le API di ricerca Enterprise:

• Metodi per richiedere dati e conteggi dei Tweet
• Autenticazione
• Paginazione
• Parametri delle richieste API ed esempi di richieste
• Payload JSON delle risposte API ed esempi di risposte
• Codici di risposta HTTP

Le API Enterprise forniscono accesso a bassa latenza, ad alta fedeltà e basato su query all’archivio dei Tweet. L’unica differenza tra le due API è l’intervallo temporale in cui è possibile effettuare ricerche: gli ultimi 30 giorni oppure a partire dal 2006. Gli intervalli temporali possono essere specificati con granularità al minuto. I dati dei Tweet sono restituiti in ordine cronologico inverso, a partire dal Tweet più recente che corrisponde alla tua query. I Tweet sono disponibili tramite l’API di ricerca circa 30 secondi dopo la pubblicazione.

​

Metodi

L’URI di base per la ricerca Enterprise è https://gnip-api.x.com/search/.

Metodo	Descrizione
POST /search/:product/accounts/:account_name/:label	Recupera i Tweet degli ultimi 30 giorni che corrispondono alla regola PowerTrack specificata.
POST /search/:product/accounts/:account_name/:label/counts	Recupera il numero di Tweet degli ultimi 30 giorni che corrispondono alla regola PowerTrack specificata.

Dove:

• :product indica l’endpoint di ricerca a cui invii le richieste, 30day oppure fullarchive.
• :account_name è il nome (case-sensitive) associato al tuo account, come visualizzato su console.gnip.com
• :label è l’etichetta (case-sensitive) associata al tuo endpoint di ricerca, come visualizzato su console.gnip.com

Ad esempio, se l’account TwitterDev dispone del prodotto di ricerca 30‑day con un’etichetta “prod” (abbreviazione di produzione), gli endpoint di ricerca sarebbero:

• Endpoint dati: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json
• Endpoint conteggi: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json

Il tuo endpoint completo dell’API di ricerca Enterprise è riportato su https://console.gnip.com.

Di seguito sono riportati alcuni esempi di richieste che utilizzano una semplice utility HTTP chiamata curl. Questi esempi usano URL con :product, :account_name e :label. Per utilizzarli, assicurati di aggiornare gli URL con i tuoi dati.

​

Autenticazione

Tutte le richieste alle API di ricerca Enterprise devono utilizzare l’autenticazione HTTP Basic, basata su una combinazione valida di indirizzo email e password usata per accedere al proprio account su https://console.gnip.com. Le credenziali devono essere inviate nell’header Authorization per ogni richiesta.

​

Comportamento di richiesta/risposta

Utilizzando i parametri fromDate e toDate, puoi richiedere qualsiasi periodo supportato dall’API. La 30-Day search API fornisce Tweet degli ultimi 31 giorni (anche se chiamata “30-Day” API, rende disponibili 31 giorni per consentire richieste relative a un mese completo). La Full-Archive search API fornisce Tweet fino al primissimo tweet (21 marzo 2006). Tuttavia, una singola risposta sarà limitata al minore tra il valore specificato in maxResults o 31 giorni. Se i dati corrispondenti o l’intervallo temporale superano il maxResults specificato o 31 giorni, riceverai un token next che dovrai usare per impaginare il resto dell’intervallo temporale richiesto.

Ad esempio, supponiamo che tu stia usando la Full-Archive search e desideri tutti i Tweet che corrispondono alla tua query dal 1° gennaio 2017 al 30 giugno 2017. Specificherai l’intero periodo di sei mesi nella richiesta utilizzando i parametri fromDate e toDate. La search API risponderà con la prima “pagina” di Tweet, con il numero di Tweet definito dal parametro maxResults (che per impostazione predefinita è 100). Presumendo che ci siano altri Tweet (e molto probabilmente ce ne saranno), l’API fornirà anche un token next che ti consente di effettuare una richiesta per la “pagina” successiva di dati. Questo processo si ripete finché l’API non restituisce più un token next. Consulta la sezione successiva per ulteriori dettagli.

​

Paginazione

Quando si effettuano richieste sia dei dati sia dei conteggi, è probabile che ci siano più informazioni di quante se ne possano restituire in una singola risposta. In tal caso, la risposta includerà un token “next”. Il token “next” è fornito come attributo JSON a livello radice. Ogni volta che viene fornito un token “next”, ci sono dati aggiuntivi da recuperare, quindi sarà necessario continuare a effettuare richieste all’API.

Nota: Il comportamento del token “next” differisce leggermente tra le richieste dei dati e quelle dei conteggi; entrambi sono descritti di seguito, con risposte di esempio fornite nella sezione API Reference.

Paginazione dei dati

Le richieste di dati probabilmente restituiranno più informazioni di quante possano essere incluse in una singola risposta. Ogni richiesta prevede un parametro che imposta il numero massimo di Tweet da restituire per richiesta. Il parametro maxResults è impostato per impostazione predefinita su 100 e può assumere valori compresi tra 10 e 500. Se la tua query produce più Tweet di quanti consentiti dal parametro ‘maxResults’ specificato nella richiesta, la risposta includerà un token ‘next’ (come attributo JSON al livello radice). Questo token ‘next’ viene utilizzato nella richiesta successiva per recuperare la porzione successiva dei Tweet corrispondenti a quella query (cioè la “pagina” successiva). I token ‘next’ continueranno a essere forniti finché non avrai raggiunto l’ultima “pagina” di risultati per quella query, momento in cui non verrà più restituito alcun token ‘next’.

Per richiedere la “pagina” successiva di dati, devi effettuare esattamente la stessa query dell’originale, inclusi i parametri query, toDate e fromDate, se utilizzati, e includere anche un parametro di richiesta ‘next’ impostato al valore ottenuto dalla risposta precedente. Questo meccanismo può essere usato sia con una richiesta GET sia con una richiesta POST. Tuttavia, nel caso di una richiesta GET, il parametro ‘next’ deve essere codificato nell’URL.

Puoi continuare a passare l’elemento ‘next’ dalla tua query precedente finché non avrai ricevuto tutti i Tweet relativi al periodo di tempo coperto dalla query. Quando ricevi una risposta che non include un elemento ‘next’, significa che hai raggiunto l’ultima pagina e non sono disponibili ulteriori dati per la query e l’intervallo temporale specificati.

Paginazione dei conteggi

L’endpoint ‘counts’ fornisce i volumi di Tweet associati a una query su base giornaliera, oraria o al minuto. L’endpoint API ‘counts’ restituirà un array con timestamp dei conteggi per un massimo di 31 giorni di payload. Se richiedi più di 31 giorni di conteggi, ti verrà fornito un token ‘next’. Come per i token ‘next’ di data, devi inviare esattamente la stessa query dell’originale e includere anche un parametro di richiesta ‘next’ impostato al valore della risposta precedente.

Oltre alle richieste superiori a 31 giorni di conteggi, esiste un altro scenario in cui viene fornito un token ‘next’. Per query ad alto volume, è possibile che la generazione dei conteggi richieda abbastanza tempo da causare un timeout della risposta. Quando ciò si verifica, riceverai meno di 31 giorni di conteggi, ma ti verrà fornito un token ‘next’ per continuare a effettuare richieste per l’intero payload di conteggi. Importante: I timeout restituiscono solo “bucket” completi, quindi 2,5 giorni produrrebbero 2 “bucket” giornalieri completi.

Note aggiuntive

• Quando si utilizza fromDate o toDate in una richiesta di ricerca, si otterranno risultati solo all’interno dell’intervallo temporale specificato. Una volta raggiunto l’ultimo gruppo di risultati nel tuo intervallo, non verrà restituito alcun token ‘next’.
• L’elemento ‘next’ può essere utilizzato con qualsiasi valore di maxResults compreso tra 10 e 500 (valore predefinito: 100). Il parametro maxResults determina quanti Tweet vengono restituiti in ogni risposta, ma non impedisce di ottenere tutti i risultati nel complesso.
• L’elemento ‘next’ non scade. Più richieste che utilizzano la stessa ‘next’ query riceveranno gli stessi risultati, indipendentemente da quando viene effettuata la richiesta.
• Durante la paginazione dei risultati tramite il parametro ‘next’, è possibile incontrare duplicati ai margini della query. L’applicazione dovrebbe gestirli in modo tollerante.

​

Endpoint dei dati

POST /search/:product/:label

Schema dell’endpoint:

Questo endpoint restituisce i data per la query e l’intervallo di tempo specificati. Se non viene specificato un intervallo di tempo, i parametri temporali predefiniti saranno impostati sugli ultimi 30 giorni. Nota: Questa funzionalità può essere ottenuta anche con una richiesta GET, invece di POST, codificando nell’URL i parametri descritti di seguito.

Parametri della richiesta dati

Parameters	Description	Required	Sample Value
query	L’equivalente di una regola PowerTrack, fino a 2.048 caratteri (senza limiti al numero di clausole positive e negative). Questo parametro deve includere TUTTE le parti della regola PowerTrack, compresi tutti gli operatori; le parti della regola non devono essere suddivise in altri parametri della query. Nota: Non tutti gli operatori PowerTrack sono supportati. Gli operatori supportati sono elencati QUI.	Yes	(snow OR cold OR blizzard) weather
tag	I tag possono essere usati per suddividere le regole e i relativi dati corrispondenti in diversi gruppi logici. Se viene fornito un tag di regola, esso è incluso nell’attributo ‘matching_rules’. Si consiglia di assegnare UUID specifici della regola ai tag e di mantenere le mappature desiderate lato client.	No	8HYG54ZGTU
fromDate	Il timestamp UTC meno recente (fino al 21/03/2006 con la ricerca Full-Archive) a partire dal quale verranno forniti i Tweet. Il timestamp ha granularità al minuto ed è inclusivo (ad es. 12:00 include il minuto 00). Specificato: Usare solo fromDate senza il parametro toDate restituirà risultati per la query andando a ritroso nel tempo da now( ) fino a fromDate. Non specificato: Se non viene specificato fromDate, l’API fornirà tutti i risultati relativi ai 30 giorni precedenti a now( ) o a toDate (se specificato). Se non viene utilizzato né fromDate né toDate, l’API fornirà tutti i risultati degli ultimi 30 giorni, a partire dal momento della richiesta, andando a ritroso.	No	201207220000
toDate	Il timestamp UTC più recente fino al quale verranno forniti i Tweet. Il timestamp ha granularità al minuto e non è inclusivo (ad es. 11:59 non include il 59º minuto dell’ora). Specificato: Usare solo toDate senza il parametro fromDate restituirà i 30 giorni di dati più recenti precedenti a toDate. Non specificato: Se non viene specificato toDate, l’API fornirà tutti i risultati da now( ) per la query andando a ritroso nel tempo fino a fromDate. Se non viene utilizzato né fromDate né toDate, l’API fornirà tutti i risultati dell’intero indice di 30 giorni, a partire dal momento della richiesta, andando a ritroso.	No	201208220000
maxResults	Il numero massimo di risultati di ricerca restituiti da una richiesta. Un numero compreso tra 10 e il limite di sistema (attualmente 500). Per impostazione predefinita, la risposta a una richiesta restituisce 100 risultati.	No	500
next	Questo parametro viene utilizzato per ottenere la pagina successiva di risultati come descritto QUI. Il valore usato con il parametro è prelevato direttamente dalla risposta fornita dall’API e non deve essere modificato.	No	NTcxODIyMDMyODMwMjU1MTA0

Dettagli aggiuntivi

Intervallo di disponibilità	30-Day: ultimi 31 giorni Full-Archive: 21 marzo 2006 - Presente
Formato della query	Equivalente a una regola PowerTrack, fino a 2.048 caratteri (senza limiti al numero di clausole positive e negative). Nota: Non tutti gli operatori PowerTrack sono supportati. Consulta Available operators per l’elenco degli operatori supportati.
Limite di velocità	I partner saranno soggetti a limiti di velocità sia con granularità al minuto sia al secondo. Il limite per minuto varierà in base al partner, come specificato nel contratto. Tuttavia, questi limiti per minuto non sono pensati per essere utilizzati in un singolo burst. Indipendentemente dal limite per minuto, tutti i partner saranno limitati a un massimo di 20 richieste al secondo, aggregate su tutte le richieste per data e/o conteggi.
Conformità	Tutti i dati forniti tramite la Full-Archive Search API sono conformi al momento della consegna.
Disponibilità in tempo reale	I dati sono disponibili nell’indice entro 30 secondi dalla generazione sulla piattaforma X

Esempi di richieste e risposte sui dati

Esempio di richiesta POST

• I parametri in una richiesta POST vengono inviati tramite un corpo in formato JSON, come mostrato di seguito.
• Tutte le parti della regola PowerTrack oggetto dell’interrogazione (ad es. parole chiave, altri operatori come bounding_box:) devono essere inserite nel parametro ‘query’.
• Non suddividere parti della regola in parametri separati nell’URL della query.

Di seguito è riportato un esempio di comando POST (utilizzando cURL) per effettuare una richiesta iniziale di data:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm"}'

Se la risposta dell’API include un token ‘next’, di seguito è riportato un esempio di richiesta successiva basata su quella originale, con il parametro ‘next’ impostato al token fornito:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label.json" -d '{"query":"from:twitterDev","maxResults":500,"fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm",
    "next":"NTcxODIyMDMyODMwMjU1MTA0"}'

Esempio di richiesta GET

• I parametri in una richiesta GET sono codificati nell’URL utilizzando la codifica URL standard.
• Tutte le parti della regola PowerTrack oggetto della query (ad esempio parole chiave, altri operatori come bounding_box:) devono essere inserite nel parametro ‘query’.
• Non separare parti della regola come parametri distinti nell’URL della query.

Di seguito è riportato un esempio di comando GET (con cURL) per effettuare una richiesta iniziale di data:

    curl -u<username> "http://gnip-api.x.com/search/:product/accounts/:account_name/:label.json?query=from%3Atwitterdev&maxResults=500&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"

Esempi di risposte dei data

Nota che, per i Tweet creati a partire dal 29 settembre 2022, gli oggetti Tweet includeranno i metadata di modifica del Tweet che descrivono la relativa cronologia delle modifiche. Consulta la pagina dei fondamenti “Edit Tweets” per maggiori dettagli.

Di seguito è riportato un esempio di risposta a una query dei data. Questo esempio presuppone che fossero disponibili più di ‘maxResults’ Tweet, quindi viene fornito un token ‘next’ per le richieste successive. Se ‘maxResults’ o meno Tweet sono associati alla tua query, nella risposta non verrà incluso alcun token ‘next’. Il valore dell’elemento ‘next’ cambierà a ogni query e deve essere trattato come una stringa opaca. L’elemento ‘next’ apparirà come segue nel corpo della risposta:

{
    "results":
      [
            {--Tweet 1--},
            {--Tweet 2--},
            ...
            {--Tweet 500--}
      ],
    "next":"NTcxODIyMDMyODMwMjU1MTA0",
    "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }

La risposta a una richiesta successiva potrebbe presentarsi come segue (nota i nuovi Tweet e il diverso valore di “next”):

{
      "results":
      [
            {--Tweet 501--},
            {--Tweet 502--},
            ...
            {--Tweet 1000--}
      ],
      "next":"R2hCDbpBFR6eLXGwiRF1cQ",
      "requestParameters":
      {
        "maxResults":500,
        "fromDate":"201101010000",
        "toDate":"201201010000"
      }
  }

Puoi continuare a passare l’elemento ‘next’ dalla query precedente finché non avrai ricevuto tutti i Tweet per il periodo coperto dalla tua query. Quando ricevi una risposta che non include l’elemento ‘next’, significa che hai raggiunto l’ultima pagina e non sono disponibili ulteriori dati nell’intervallo temporale specificato.

​

endpoint conteggi

/search/:stream/counts

Modello di endpoint:

/search/fullarchive/accounts/:account_name/:label/counts.json

Questo endpoint restituisce i dati dei conteggi (volumi di dati) per la query specificata. Se non viene specificato un intervallo temporale, i parametri di tempo predefiniti corrisponderanno agli ultimi 30 giorni. I volumi di dati vengono restituiti come un array con timestamp su base giornaliera, oraria (predefinita) o al minuto.

Nota: Questa funzionalità può essere ottenuta anche utilizzando una richiesta GET, invece di una POST, codificando nell’URL i parametri descritti di seguito.

Parametri della richiesta Counts

Parameters	Description	Required	Sample Value
query	L’equivalente di una regola PowerTrack, fino a 2.048 caratteri (senza limiti al numero di clausole positive e negative). Questo parametro deve includere TUTTE le parti della regola PowerTrack, inclusi tutti gli operatori; le parti della regola non devono essere suddivise in altri parametri della query. Nota: Non tutti gli operatori PowerTrack sono supportati. Consulta Available operators per l’elenco degli operatori supportati.	Yes	(snow OR cold OR blizzard) weather
fromDate	Il timestamp UTC meno recente (fino al 21/03/2006) a partire dal quale verranno forniti i Tweet. Il timestamp ha granularità al minuto ed è inclusivo (es.: 12:00 include il minuto 00). Specificato: Utilizzando solo fromDate senza il parametro toDate, l’API fornirà i conteggi (volumi di dati) per la query andando a ritroso nel tempo da ora fino a fromDate. Se fromDate è antecedente di oltre 31 giorni rispetto a ora, riceverai un next token per scorrere la richiesta per pagine. Non specificato: Se non viene specificato un fromDate, l’API fornirà i conteggi (volumi di dati) per i 30 giorni precedenti a ora oppure a toDate (se specificato). Se non viene utilizzato né fromDate né toDate, l’API fornirà i conteggi (volumi di dati) per gli ultimi 30 giorni, a partire dal momento della richiesta, andando a ritroso.	No	201207220000
toDate	Il timestamp UTC più recente fino al quale verranno forniti i Tweet. Il timestamp ha granularità al minuto e non è inclusivo (es.: 11:59 non include il 59º minuto dell’ora). Specificato: Utilizzando solo toDate senza il parametro fromDate verranno forniti i conteggi più recenti (volumi di dati) per i 30 giorni precedenti a toDate. Non specificato: Se non viene specificato un toDate, l’API fornirà i conteggi (volumi di dati) per la query andando a ritroso nel tempo fino a fromDate. Se fromDate è antecedente di oltre 31 giorni rispetto a ora, riceverai un next token per scorrere la richiesta per pagine. Se non viene utilizzato né fromDate né toDate, l’API fornirà i conteggi (volumi di dati) per gli ultimi 30 giorni, a partire dal momento della richiesta, andando a ritroso.	No	201208220000
bucket	L’unità di tempo per la quale verranno forniti i dati di conteggio. I dati possono essere restituiti per ogni giorno, ora o minuto nell’intervallo richiesto. Per impostazione predefinita, verranno forniti conteggi orari. Opzioni: ‘day’, ‘hour’, ‘minute’	No	minute
next	Questo parametro viene utilizzato per ottenere la pagina successiva dei risultati come descritto QUI. Il valore del parametro è prelevato direttamente dalla risposta dell’API e non deve essere modificato.	No	NTcxODIyMDMyODMwMjU1MTA0

Dettagli aggiuntivi

Intervallo temporale disponibile	30-Day: ultimi 31 giorni Full-Archive: 21 marzo 2006 - oggi
Formato della query	Equivalente a una regola PowerTrack, fino a 2.048 caratteri. Nota: Non tutti gli operatori PowerTrack sono supportati. Consulta Available operators per l’elenco degli operatori supportati.
Limite di velocità	I partner saranno soggetti a limiti di velocità sia al minuto sia al secondo. Il limite per minuto varierà in base al partner, come specificato nel contratto. Tuttavia, tali limiti per minuto non sono pensati per essere consumati in un singolo burst. Indipendentemente dal tuo limite per minuto, tutti i partner saranno limitati a un massimo di 20 richieste al secondo, aggregate su tutte le richieste per data e/o conteggi.
Precisione dei conteggi	I conteggi restituiti da questo endpoint riflettono il numero di Tweet effettivamente occorsi e non includono eventuali eventi di conformità successivi (eliminazioni, scrub geos). Alcuni Tweet conteggiati potrebbero non essere disponibili tramite l’endpoint data a seguito di azioni di conformità dell’utente.

Esempi di richieste e risposte per i conteggi

Esempio di richiesta POST

• I parametri di una richiesta POST vengono inviati nel body in formato JSON, come mostrato di seguito.
• Tutte le parti della regola PowerTrack oggetto della query (ad es. parole chiave, altri operatori come bounding_box:) devono essere inserite nel parametro ‘query’.
• Non separare parti della regola in parametri distinti nell’URL della query.

Di seguito è riportato un esempio di comando POST (utilizzando cURL) per eseguire una richiesta iniziale di conteggi:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day"}'

Se la risposta dei conteggi dell’API include un token “next”, di seguito è mostrata una richiesta successiva che riprende quella originale, con il parametro “next” impostato sul token fornito:

    curl -X POST -u<username> "https://gnip-api.x.com/search/:product/accounts/:account_name/:label/counts.json" -d '{"query":"TwitterDev","fromDate":"yyyymmddhhmm","toDate":"yyyymmddhhmm","bucket":"day",
    "next":"YUcxO87yMDMyODMwMjU1MTA0"}'

Esempio di richiesta GET

• I parametri di una richiesta GET sono codificati nell’URL, utilizzando la codifica URL standard
• Tutte le parti della regola PowerTrack oggetto della query (ad es. parole chiave, altri operatori come bounding_box:) devono essere inserite nel parametro ‘query’
• Non suddividere parti della regola come parametri separati nell’URL della query

Di seguito un comando GET di esempio (utilizzando cURL) per effettuare una richiesta iniziale dei conteggi:

    curl -u<username> "http://gnip-api.x.com/search/fullarchive/accounts/:account_name/:label/counts.json?query=TwitterDev&bucket=day&fromDate=yyyymmddhhmm&toDate=yyyymmddhhmm"

​

Esempi di risposte sui conteggi

Di seguito è riportato un esempio di risposta a una query sui conteggi (volume di dati). Questo esempio di risposta include un token ‘next’, il che significa che la richiesta di conteggi copriva più di 31 giorni, oppure che la query inviata aveva un volume sufficientemente elevato da generare una risposta parziale.

Il valore dell’elemento ‘next’ varierà a ogni query e deve essere trattato come una stringa opaca. L’elemento ‘next’ apparirà come segue nel corpo della risposta:

    {
      "results": [
        { "timePeriod": "201101010000", "count": 32 },
        { "timePeriod": "201101020000", "count": 45 },
        { "timePeriod": "201101030000", "count": 57 },
        { "timePeriod": "201101040000", "count": 123 },
        { "timePeriod": "201101050000", "count": 134 },
        { "timePeriod": "201101060000", "count": 120 },
        { "timePeriod": "201101070000", "count": 43 },
        { "timePeriod": "201101080000", "count": 65 },
        { "timePeriod": "201101090000", "count": 85 },
        { "timePeriod": "201101100000", "count": 32 },
        { "timePeriod": "201101110000", "count": 23 },
        { "timePeriod": "201101120000", "count": 85 },
        { "timePeriod": "201101130000", "count": 32 },
        { "timePeriod": "201101140000", "count": 95 },
        { "timePeriod": "201101150000", "count": 109 },
        { "timePeriod": "201101160000", "count": 34 },
        { "timePeriod": "201101170000", "count": 74 },
        { "timePeriod": "201101180000", "count": 24 },
        { "timePeriod": "201101190000", "count": 90 },
        { "timePeriod": "201101200000", "count": 85 },
        { "timePeriod": "201101210000", "count": 93 },
        { "timePeriod": "201101220000", "count": 48 },
        { "timePeriod": "201101230000", "count": 37 },
        { "timePeriod": "201101240000", "count": 54 },
        { "timePeriod": "201101250000", "count": 52 },
        { "timePeriod": "201101260000", "count": 84 },
        { "timePeriod": "201101270000", "count": 120 },
        { "timePeriod": "201101280000", "count": 34 },
        { "timePeriod": "201101290000", "count": 83 },
        { "timePeriod": "201101300000", "count": 23 },
        { "timePeriod": "201101310000", "count": 12 }
       ],
      "totalCount":2027,
      "next":"NTcxODIyMDMyODMwMjU1MTA0",
      "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }

La risposta a una richiesta successiva potrebbe presentarsi come segue (si notino la nuova timeline dei conteggi e il diverso valore di ‘next’):

    {
      "results": [
        { "timePeriod": "201102010000", "count": 45 },
        { "timePeriod": "201102020000", "count": 76 },
         ....
        { "timePeriod": "201103030000", "count": 13 }
     ],
     "totalCount":3288,
     "next":"WE79fnakFanyMDMyODMwMjU1MTA0",
     "requestParameters":
        {
          "bucket":"day",
          "fromDate":"201101010000",
          "toDate":"201201010000"
        }
    }

Puoi continuare a passare l’elemento ‘next’ dalla query precedente finché non avrai ricevuto tutti i conteggi per l’intervallo temporale della query. Quando ricevi una risposta che non include l’elemento ‘next’, significa che hai raggiunto l’ultima pagina e non sono disponibili ulteriori conteggi nel tuo intervallo temporale.

​

Codici di risposta HTTP

Status	Text	Description
200	OK	La richiesta è stata eseguita correttamente. La risposta JSON sarà simile alla seguente:
400	Bad Request	In genere questa risposta si verifica per la presenza di JSON non valido nella richiesta o quando la richiesta non invia alcun payload JSON.
401	Unauthorized	L’autenticazione HTTP non è riuscita a causa di credenziali non valide. Accedi a console.gnip.com con le tue credenziali per verificare di utilizzarle correttamente nella richiesta.
404	Not Found	La risorsa non è stata trovata all’URL a cui è stata inviata la richiesta, probabilmente perché è stato utilizzato un URL errato.
422	Unprocessable Entity	Restituito a causa di parametri non validi nel parametro query (ad es. regole PowerTrack non valide).
429	Unknown Code	La tua App ha superato il limite per le richieste di connessione. Il messaggio JSON corrispondente sarà simile al seguente:
500	Internal Server Error	Si è verificato un errore lato server. Riprova la richiesta utilizzando un criterio di backoff esponenziale.
502	Proxy Error	Si è verificato un errore lato server. Riprova la richiesta utilizzando un criterio di backoff esponenziale.
503	Service Unavailable	Si è verificato un errore lato server. Riprova la richiesta utilizzando un criterio di backoff esponenziale.