API de Busca: Enterprise

Atenção: Lançamos uma nova versão de busca de Posts e de contagem de Posts na X API v2. Recomendamos que você confira as novidades da X API v2. Esses endpoints foram atualizados para incluir metadata de edição de Post. Saiba mais sobre essa metadata na página de fundamentos “Editar Posts”.

Visão geral

Enterprise As APIs Enterprise estão disponíveis apenas em nossos níveis de acesso gerenciado. Para usar essas APIs, você deve primeiro configurar uma conta com nossa equipe de vendas Enterprise. Para saber mais, consulte AQUI. Você pode ver todas as ofertas de pesquisa de Post da X API AQUI. Há duas APIs de pesquisa Enterprise:

A 30-Day Search API fornece dados dos últimos 30 dias.
A Full-Archive Search API fornece acesso completo e instantâneo a todo o corpus de dados da X, desde o primeiro Post em março de 2006.

Essas APIs RESTful aceitam uma única query de até 2.048 caracteres por solicitação. As queries são escritas com a sintaxe de regras do PowerTrack — consulte Regras e filtragem para mais detalhes. Os usuários podem especificar qualquer período, com granularidade de minuto. No entanto, as respostas serão limitadas ao menor valor entre o seu maxResults especificado OU 31 dias e incluem um next token para paginar o próximo conjunto de resultados. Se os parâmetros de tempo não forem especificados, a API retornará data correspondente aos 30 dias mais recentes. As APIs de pesquisa Enterprise oferecem acesso de baixa latência, alta fidelidade e baseado em query ao arquivo de Posts, com granularidade de minuto. Os dados de Post são fornecidos em ordem cronológica inversa, começando pelo Post mais recente que corresponde à sua query. Os Posts ficam disponíveis na search API aproximadamente 30 segundos após serem publicados. Esses endpoints de pesquisa fornecem metadata de edição de Post. Todos os objetos de Posts criados desde 29 de setembro de 2022 incluem metadata de edição de Post, mesmo que o Post nunca tenha sido editado. Cada vez que um Post é editado, um novo ID do Post é criado. O histórico de edição de um Post é documentado por um array de IDs de Post, começando pelo ID original. Esses endpoints sempre retornam a edição mais recente, juntamente com qualquer histórico de edição. Qualquer Post coletado após sua janela de edição de 30 minutos representará sua versão final. Para saber mais sobre a metadata de Edit Post, consulte a página Fundamentos de Edit Posts. As solicitações incluem um parâmetro maxResults que especifica o número máximo de Posts a serem retornados por resposta da API. Se mais Posts estiverem associados à query do que essa quantidade máxima de resultados por resposta, um next token será incluído na resposta. Esses next tokens são usados em solicitações subsequentes para paginar por todo o conjunto de Posts associados à query. Essas APIs de pesquisa Enterprise fornecem um endpoint de counts que permite aos usuários solicitar o volume de data associado à sua query.

Tipos de solicitação

As APIs de pesquisa Enterprise oferecem suporte a dois tipos de solicitações:

Solicitações de pesquisa (data)

As solicitações às APIs de pesquisa Enterprise permitem recuperar até 500 resultados por resposta em um determinado intervalo de tempo, com possibilidade de paginação para obter dados adicionais. Usando o parâmetro maxResults, você pode definir tamanhos de página menores para casos de uso de exibição (permitindo que o usuário solicite mais resultados conforme necessário) ou tamanhos de página maiores (até 500) para extrações de dados em grande escala. Os dados são entregues em ordem cronológica inversa e estão em conformidade no momento da entrega.

Solicitações de contagem (Contagem de Posts)

As solicitações de contagem permitem recuperar contagens de atividade históricas, que refletem o número de atividades ocorridas que correspondem a uma determinada query durante o período solicitado. A resposta basicamente fornecerá um histograma de contagens, agrupadas por dia, hora ou minuto (o agrupamento padrão é hora). É importante observar que os resultados de contagem nem sempre refletem eventos de compliance (por exemplo, deletes de Posts) que acontecem muito depois (7+ dias) de a publicação de um Post; portanto, é esperado que a métrica de contagem nem sempre corresponda à de uma solicitação de data para a mesma query. Observação sobre cobrança: cada solicitação – incluindo solicitações de paginação – feita aos endpoints de data e de contagem é contabilizada como uma solicitação faturável. Portanto, se houver várias páginas de resultados para uma única query, percorrer as X páginas de resultados equivalerá a X solicitações para fins de faturamento.

Operadores disponíveis

As APIs de busca Enterprise oferecem suporte a regras com até 2.048 caracteres. As APIs de busca Enterprise oferecem suporte aos operadores listados abaixo. Para descrições detalhadas, veja AQUI.


Correspondência no conteúdo do Post:	Correspondência com contas de interesse:	Atributos do Post:	Operadores geoespaciais:
* palavra‑chave * “frase entre aspas” * “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 (operador somente de negação)	* 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:

Observações: Não incorpore/anide operadores. “#cats” será interpretado como cats nas APIs de busca. O operador ‘lang:’ e todos os operadores ‘is:’ e ‘has:’ não podem ser usados isoladamente e devem ser combinados com outra cláusula (por exemplo, @XDevelopers has:links). As APIs de busca usam um conjunto limitado de operadores devido à funcionalidade de tokenização/correspondência. As APIs Enterprise em tempo real e as de histórico em lote oferecem operadores adicionais. Veja AQUI para mais detalhes. Para mais detalhes, consulte o guia Introdução aos operadores.

Disponibilidade de dados / datas importantes

Ao usar a Full-Archive search API, lembre-se de que a plataforma X vem evoluindo desde 2006. À medida que novos recursos foram adicionados, os objetos JSON subjacentes receberam novas metadata. Por esse motivo, é importante entender quando atributos de Post foram adicionados, pois é com eles que os operadores de busca fazem correspondência. Abaixo estão algumas das datas de “nascimento” mais fundamentais de grupos importantes de metadata. Para saber mais sobre quando os atributos de Post foram introduzidos pela primeira vez, consulte este guia.

Primeiro Post: 21/3/2006
Primeiros Retweets nativos: 6/11/2009
Primeiro Post georreferenciado: 19/11/2009
URLs indexadas pela primeira vez para filtragem: 27/8/2011
metadata de expansão de URL aprimorada (títulos e descrições de sites): 1/12/2014
Enriquecimento e filtragem de Profile Geo metadata: 17/2/2015

Atualizações de dados e mutabilidade

Com as APIs de busca Enterprise, alguns dados de um Post são mutáveis, ou seja, podem ser atualizados ou alterados após o arquivamento inicial. Esses dados mutáveis se enquadram em duas categorias:

metadata do objeto de usuário:
- @handle do usuário (o id numérico nunca muda)
- Descrição da bio
- Contagens: statuses, seguidores, amigos, favoritos, Lists
- Localização do perfil
- Outros detalhes, como fuso horário e idioma
Estatísticas do Post — ou seja, qualquer coisa que possa ser alterada na plataforma por ações do usuário (exemplos abaixo):
- Contagem de favoritos
- Contagem de Retweet

Na maioria desses casos, as APIs de busca retornarão data conforme ela existe na plataforma no momento da query, e não no momento de geração do Post. No entanto, no caso de queries que usam operadores de seleção (por exemplo, from, to, @, is:verified), isso pode não ocorrer. Os dados são atualizados regularmente em nosso índice, com maior frequência para os períodos mais recentes. Como resultado, em alguns casos, os dados retornados podem não corresponder exatamente aos dados atuais exibidos em X.com, mas corresponderão aos dados do momento em que foram indexados pela última vez. Observe que esse problema de inconsistência se aplica apenas a queries em que o operador incide sobre dados mutáveis. Um exemplo é filtrar por nomes de usuário; a melhor forma de contornar isso é usar ids numéricos de usuário em vez de @handles nessas queries.

Solicitações single-thread vs. multi-thread

Cada cliente tem um limite de taxa definido para seu endpoint de busca. O limite de taxa padrão por minuto para a busca de Arquivo Completo é de 120 solicitações por minuto, com uma média de 2 queries por segundo (QPS). Essa média de QPS significa que, em teoria, 2 solicitações podem ser feitas à API a cada segundo. Dado o recurso de paginação do produto, se uma query de um ano tiver um milhão de Posts associados a ela, distribuídos uniformemente ao longo do ano, seriam necessárias mais de 2.000 solicitações (assumindo um ‘maxResults’ de 500) para receber todos os data. Supondo que cada resposta leve dois segundos, isso dá 4.000 segundos (ou pouco mais de uma hora) para obter todos esses data de forma serial/sequencial por um único thread (1 solicitação por segundo usando o token “next” da resposta anterior). Nada mal! Agora considere a situação em que doze threads paralelos são usados para receber data. Supondo uma distribuição uniforme de um milhão de Posts ao longo do período de um ano, você poderia dividir as solicitações em doze threads paralelos (multi-thread) e utilizar mais do limite de taxa por segundo para o “job” único. Em outras palavras, você poderia executar um thread por mês de interesse e, ao fazer isso, os data poderiam ser recuperados 12x mais rápido (ou ~6 minutos). Esse exemplo multi-thread se aplica igualmente bem ao endpoint de contagens. Por exemplo, se você quisesse receber contagens de Posts para um período de dois anos, poderia fazer uma solicitação single-thread e paginar pelas contagens em intervalos de 31 dias. Supondo que cada resposta leve 2 segundos, levaria aproximadamente 48 segundos para fazer as 24 solicitações à API e recuperar o conjunto completo de contagens. No entanto, você também tem a opção de fazer várias solicitações de um mês por vez. Ao fazer 12 solicitações por segundo, o conjunto completo de contagens poderia ser recuperado em aproximadamente 2 segundos.

Lógica de novas tentativas

Se você encontrar um erro 503 com as APIs de busca Enterprise, é provável que seja um erro temporário e que possa ser resolvido tentando novamente a solicitação após um curto período. Se a solicitação falhar 4 vezes consecutivas e você tiver aguardado pelo menos 10 minutos entre as falhas, siga as etapas a seguir para solucionar o problema:

Tente novamente após reduzir o intervalo de tempo coberto pela solicitação. Se necessário, repita até chegar a uma janela de 6 horas.
Se você estiver usando OR para combinar um grande número de termos, divida-os em regras separadas e tente cada uma individualmente.
Se você estiver usando muitas exclusões na sua regra, reduza a quantidade de termos negados e tente novamente.

Introdução rápida

Introdução à enterprise Search Posts: 30-Day API

A enterprise Search Posts: 30-Day API fornece Posts publicados nos últimos 30 dias. Os Posts são identificados e retornados com base na query que você especificar na solicitação. Uma query é uma regra na qual você define o que o Post retornado deve conter. Neste tutorial, pesquisaremos Posts originados da conta da X @XDevelopers, em inglês. Os Posts que você recebe no payload podem estar em formato data, que fornece o payload completo do Post, ou em formato counts, que fornece dados numéricos de contagem de Posts correspondidos. Usaremos cURL para fazer solicitações aos endpoints data e counts. Você precisará do seguinte:

[Uma conta Enterprise]https://developer.x.com/en/products/x-api/enterprise
Seu nome de usuário, senha e nome da conta
Rótulo associado ao seu endpoint de pesquisa, conforme exibido em console.gnip.com

Acessando o endpoint de data

O endpoint de data fornecerá o payload completo de Post dos Posts correspondentes. Usaremos os operadores from: e lang: para encontrar Posts publicados por @XDevelopers em inglês. Para mais operadores, clique aqui.

cURL
cURL example

cURL é uma ferramenta de linha de comando para obter ou enviar arquivos usando a sintaxe de URL.Copie a seguinte solicitação cURL no seu terminal após fazer as seguintes alterações:

Username <USERNAME> por exemplo, email@domain.com
Account name <ACCOUNT-NAME> por exemplo, john-doe
Label <LABEL> por exemplo, prod
fromDate e toDate por exemplo, "fromDate":"201811010000", "toDate":"201811122359"

Após enviar sua solicitação, será solicitado que você informe sua senha.

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 de resposta do endpoint de dados

O payload retornado pela sua solicitação à API será exibido em formato JSON, conforme mostrado abaixo.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"O crowdsourcing inovador que a colaboração Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relevantes…",
			"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": "Sua fonte oficial para notícias, atualizações e eventos da Plataforma Twitter. Precisa de ajuda técnica? Visite 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": "\"O crowdsourcing inovador que a colaboração Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relev… 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 de Produto na @Tagboard. Trabalhou com Dados, negócios e produto na @Klout e para @LithiumTech; membro do conselho @BBI; consultor @Insightpool. O pior desenhista de quadro branco do mundo.",
					"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": "\"O crowdsourcing inovador que a colaboração Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relevantes em tempo real e permitindo que eleitores façam perguntas durante debates,\" -- @adamostrow, @TEGNA\nSaiba Mais: 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 Colaboram para Trazer o Melhor Conteúdo Eleitoral para Veículos de Notícias com Tagboard…",
									"description": "Por Tyler Singletary, Chefe de Produto, 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"
	}
}

Acessando o endpoint de contagens

Com o endpoint de contagens, vamos recuperar o número de Posts originados da conta @XDevelopers em inglês, agrupados por day.

cURL
cURL example

cURL é uma ferramenta de linha de comando para obter ou enviar arquivos usando a sintaxe de URL.Copie a solicitação cURL abaixo no seu terminal após ajustar os seguintes itens:

Username <USERNAME> por exemplo, email@domain.com
Account name <ACCOUNT-NAME> por exemplo, john-doe
Label <LABEL> por exemplo, prod
fromDate e toDate por exemplo, "fromDate":"201811010000", "toDate":"201811122359"

Ao enviar sua solicitação, será solicitado que você informe sua senha.

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 de resposta do endpoint Counts

O payload retornado pela sua solicitação à API será exibido em formato JSON, conforme mostrado abaixo.

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

Ótimo trabalho! Agora você acessou com sucesso a API Enterprise Search Posts: 30-Day.

Introdução ao uso da Enterprise Search Posts: Full-Archive API

A Enterprise Search Posts: Full-Archive API fornece Posts desde o primeiro publicado em 2006. Os Posts são identificados e retornados com base na query que você especificar na solicitação. Uma query é uma regra na qual você define o que o Post retornado deve conter. Neste tutorial, buscaremos Posts originados da conta da X @XDevelopers em inglês. Os Posts retornados no payload podem estar no formato data, que fornece o payload completo do Post, ou no formato counts, que oferece dados numéricos de contagem de Posts correspondentes. Usaremos cURL para fazer solicitações aos endpoints de data e counts. Você precisará do seguinte:

Uma conta Enterprise — https://developer.x.com/en/products/x-api/enterprise
Seu nome de usuário, senha e nome da conta
Rótulo associado ao seu endpoint de pesquisa, conforme exibido em console.gnip.com

cURL
cURL example

cURL é uma ferramenta de linha de comando para obter ou enviar arquivos usando a sintaxe de URL.Copie a solicitação cURL a seguir no seu terminal após fazer as seguintes alterações:

Nome de usuário <USERNAME> por exemplo: email@domain.com
Nome da conta <ACCOUNT-NAME> por exemplo: john-doe
Label <LABEL> por exemplo: prod
fromDate e toDate por exemplo: "fromDate":"201802010000", "toDate":"201802282359"

Ao enviar sua solicitação, será solicitada a sua senha.

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 de resposta do endpoint de dados

O payload retornado pela sua solicitação à API será apresentado em formato JSON, conforme mostrado abaixo.

{
	"results": [
		{
			"created_at": "Fri Nov 02 17:18:31 +0000 2018",
			"id": 1058408022936977409,
			"id_str": "1058408022936977409",
			"text": "RT @harmophone: \"O crowdsourcing inovador que a colaboração entre Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relevantes…",
			"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": "Sua fonte oficial para notícias, atualizações e eventos da Plataforma Twitter. Precisa de ajuda técnica? Visite 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": "\"O crowdsourcing inovador que a colaboração entre Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relev… 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 de Produto na @Tagboard. Trabalhou com Dados, negócios e produto na @Klout e para @LithiumTech; membro do conselho @BBI; consultor @Insightpool. O pior desenhista de quadro branco do mundo.",
					"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": "\"O crowdsourcing inovador que a colaboração entre Tagboard, Twitter e TEGNA possibilita está revelando conversas localmente relevantes em tempo real e permitindo que eleitores façam perguntas durante debates,\" -- @adamostrow, @TEGNA\nSaiba Mais: 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 Colaboram para Trazer o Melhor Conteúdo Eleitoral para Veículos de Notícias com Tagboard…",
									"description": "Por Tyler Singletary, Chefe de Produto, 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"
	}
}

Acessando o endpoint de contagens

Com o endpoint de contagens, vamos obter o número de Posts originados da conta @XDevelopers em inglês, agrupados por day.

cURL
cURL example

cURL é uma ferramenta de linha de comando para receber ou enviar arquivos usando a sintaxe de URL.Copie a solicitação cURL a seguir no seu terminal após fazer as seguintes alterações:

Username <USERNAME>, por exemplo, email@domain.com
Account name <ACCOUNT-NAME>, por exemplo, john-doe
Label <LABEL>, por exemplo, prod
fromDate e toDate, por exemplo, "fromDate":"201802010000", "toDate":"201802282359"

Ao enviar sua solicitação, será solicitado que você digite sua senha.

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 de resposta do endpoint Counts

O payload retornado da sua solicitação à API será exibido em formato JSON, conforme mostrado abaixo.

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

Ótimo trabalho! Agora você acessou com sucesso a API Enterprise Search Posts: Full-Archive.

Guias

Criando consultas de pesquisa

Operadores do Enterprise

Abaixo está a lista de todos os operadores com suporte nas APIs de pesquisa Enterprise da X:

API de pesquisa de 30 dias do Enterprise
API de pesquisa de arquivo completo do Enterprise

Para uma comparação lado a lado dos operadores disponíveis por produto, consulte AQUI.

Operador	Descrição
keyword	Encontra uma palavra-chave tokenizada no corpo ou URLs de um Post. Esta é uma correspondência tokenizada, o que significa que sua string de palavra-chave será comparada ao texto tokenizado do corpo do Post – a tokenização é baseada em pontuação, símbolos e caracteres separadores do plano básico Unicode. Por exemplo, um Post com o texto “I like coca-cola” seria dividido nos seguintes tokens: I, like, coca, cola. Esses tokens seriam então comparados à string de palavra-chave usada em sua regra. Para encontrar strings contendo pontuação (por exemplo, coca-cola), símbolos ou caracteres separadores, você deve usar uma correspondência exata entre aspas conforme descrito abaixo. Observação: Com a API de Pesquisa, caracteres acentuados e especiais são normalizados para caracteres latinos padrão, o que pode alterar significados em idiomas estrangeiros ou retornar resultados inesperados: Por exemplo, “músic” encontrará “music” e vice-versa. Por exemplo, frases comuns como “Feliz Año Nuevo!” em espanhol seriam indexadas como “Feliz Ano Nuevo”, o que altera o significado da frase. Observação: Este operador encontrará tanto URLs quanto URLs expandidas dentro de um Post.
emoji	Encontra um emoji no corpo de um Post. Emojis são uma correspondência tokenizada, o que significa que seu emoji será comparado ao texto tokenizado do corpo do Post – a tokenização é baseada em pontuação, símbolos/emojis e caracteres separadores do plano básico Unicode. Por exemplo, um Post com o texto “I like ” seria dividido nos seguintes tokens: I, like, . Esses tokens seriam então comparados ao emoji usado em sua regra. Observe que se um emoji tem uma variante, você deve usar “aspas” para adicioná-lo a uma regra.
”correspondência de frase exata”	Encontra a frase tokenizada e ordenada no corpo ou URLs de um Post. Esta é uma correspondência tokenizada, o que significa que sua string de palavra-chave será comparada ao texto tokenizado do corpo do Post – a tokenização é baseada em pontuação, símbolos e caracteres separadores do plano básico Unicode. Observação: A pontuação não é tokenizada e é tratada como espaço em branco. Por exemplo, “#hashtag” entre aspas encontrará “hashtag” mas não #hashtag (use o operador hashtag # sem aspas para encontrar hashtags reais). Por exemplo, “ $cashtag" entre aspas encontrará "cashtag" mas não$ cashtag (use o operador cashtag $ sem aspas para encontrar cashtags reais). Por exemplo, “Love Snow” encontrará “#love #snow” Por exemplo, “#Love #Snow” encontrará “love snow” Observação: Este operador encontrará tanto URLs quanto URLs expandidas dentro de um Post.
”keyword1 keyword2”~N	Comumente chamado de operador de proximidade, encontra um Post onde as palavras-chave estão a no máximo N tokens uma da outra. Se as palavras-chave estão em ordem inversa, elas não podem estar a mais de N-2 tokens uma da outra. Pode ter qualquer número de palavras-chave entre aspas. N não pode ser maior que 6. Observe que este operador está disponível apenas nas APIs de pesquisa `enterprise`.
from:	Encontra qualquer Post de um usuário específico. O valor deve ser o ID numérico da Conta X do usuário ou nome de usuário (excluindo o caractere @). Consulte AQUI ou AQUI para métodos de busca de IDs numéricos de Conta X.
to:	Encontra qualquer Post que é uma resposta a um usuário específico. O valor deve ser o ID numérico da Conta do usuário ou nome de usuário (excluindo o caractere @). Consulte AQUI para métodos de busca de IDs numéricos de Conta X.
url:	Executa uma correspondência tokenizada (palavra-chave/frase) nas URLs expandidas de um Post (similar ao url_contains). Tokens e frases contendo pontuação ou caracteres especiais devem estar entre aspas duplas. Por exemplo, url:“/developer”. Embora geralmente não seja recomendado, se você quiser encontrar um protocolo específico, coloque entre aspas duplas: url:“https://developer.x.com”. Observação: Ao usar PowerTrack ou Historical PowerTrack, este operador encontrará URLs contidas no Post original de um Quote Post. Por exemplo, se sua regra inclui url:“developer.x.com”, e um Post contém essa URL, quaisquer Quote Tweets desse Post serão incluídos nos resultados. Este não é o caso ao usar a API de Pesquisa.
#	Encontra qualquer Post com a hashtag fornecida. Este operador executa uma correspondência exata, NÃO uma correspondência tokenizada, o que significa que a regra “2016” encontrará posts com a hashtag exata “2016”, mas não aqueles com a hashtag “2016election” Observação: o operador hashtag depende da extração de entidades do X para encontrar hashtags, em vez de extrair a hashtag do próprio corpo. Consulte AQUI para mais informações sobre os atributos JSON de Entidades X.
@	Encontra qualquer Post que menciona o nome de usuário fornecido. O operador to: retorna uma correspondência de subconjunto do operador @mention.
$	Encontra qualquer Post que contém o ‘cashtag’ especificado (onde o caractere inicial do token é o caractere ’$’). Observe que o operador cashtag depende da extração de entidades ‘symbols’ do X para encontrar cashtags, em vez de tentar extrair o cashtag do próprio corpo. Consulte AQUI para mais informações sobre os atributos JSON de Entidades X. Observe que este operador está disponível apenas nas APIs de pesquisa `enterprise`.
retweets_of:	Alias disponível: retweets_of_user: Encontra Posts que são retweets de um usuário especificado. Aceita tanto nomes de usuário quanto IDs numéricos de Conta X (NÃO IDs de status de Post). Consulte AQUI para métodos de busca de IDs numéricos de Conta X.
lang:	Encontra Posts que foram classificados pelo X como sendo de um idioma específico (se, e somente se, o post foi classificado). É importante observar que cada Post é atualmente classificado como sendo de apenas um idioma, então usar AND com múltiplos idiomas não produzirá resultados. Observação: se nenhuma classificação de idioma puder ser feita, o resultado fornecido é ‘und’ (para indefinido). A lista abaixo representa os idiomas atualmente suportados e seu identificador de idioma BCP 47 correspondente:


Amárico: am	Alemão: de	Malaiala: ml	Eslovaco: sk
Árabe: ar	Grego: el	Maldívio: dv	Esloveno: sl
Armênio: hy	Guzerate: gu	Marata: mr	Curdo Sorâni: ckb
Basco: eu	Crioulo haitiano: ht	Nepalês: ne	Espanhol: es
Bengali: bn	Hebraico: iw	Norueguês: no	Sueco: sv
Bósnio: bs	Hindi: hi	Oriá: or	Tagalo: tl
Búlgaro: bg	Hindi romanizado: hi-Latn	Punjabi: pa	Tâmil: ta
Birmanês: my	Húngaro: hu	Pachto: ps	Telugo: te
Croata: hr	Islandês: is	Persa: fa	Tailandês: th
Catalão: ca	Indonésio: in	Polonês: pl	Tibetano: bo
Tcheco: cs	Italiano: it	Português: pt	Chinês tradicional: zh-TW
Dinamarquês: da	Japonês: ja	Romeno: ro	Turco: tr
Holandês: nl	Canarim: kn	Russo: ru	Ucraniano: uk
Inglês: en	Khmer: km	Sérvio: sr	Urdu: ur
Estoniano: et	Coreano: ko	Chinês simplificado: zh-CN	Uigur: ug
Finlandês: fi	Lao: lo	Sindi: sd	Vietnamita: vi
Francês: fr	Letão: lv	Cingalês: si	Galês: cy
Georgiano: ka	Lituano: lt


place:	Corresponde a Posts marcados com a localização especificada ou com o X place ID (veja exemplos). Nomes de lugares com várias palavras (“New York City”, “Palo Alto”) devem estar entre aspas. Observação: Consulte o endpoint público da API GET geo/search para saber como obter X place IDs. Observação: Este operador não retornará correspondência em Retweets, pois os lugares dos Retweets estão anexados ao Post original. Também não corresponderá a lugares anexados ao Post original de um Quote Tweet.
place_country:	Corresponde a Posts em que o código do país associado a um place marcado corresponde ao código ISO alfa-2 informado. Códigos ISO válidos podem ser encontrados aqui: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Observação: Este operador não retornará correspondência em Retweets, pois os lugares dos Retweets estão anexados ao Post original. Também não corresponderá a lugares anexados ao Post original de um Quote Tweet.
point_radius:[lon lat radius]	Corresponde à Localização Exata (x,y) do Post, quando presente, e, no X, a um polígono geográfico “Place”, em que o Place esteja totalmente contido na região definida. * As unidades de raio compatíveis são milhas (mi) e quilômetros (km). * O raio deve ser menor que 25 mi. * A longitude está no intervalo de ±180. * A latitude está no intervalo de ±90. * Todas as coordenadas estão em graus decimais. * Os argumentos da regra devem estar entre colchetes, separados por espaço. Observação: Este operador não retornará correspondência em Retweets, pois os lugares dos Retweets estão anexados ao Post original. Também não corresponderá a lugares anexados ao Post original de um Quote Tweet.
bounding_box:[west_long south_lat east_long north_lat]	Alias disponível: geo_bounding_box: Corresponde à Localização Exata (long, lat) do Post, quando presente, e, no X, a um polígono geográfico “Place”, em que o Place esteja totalmente contido na região definida. * west_long e south_lat representam o canto sudoeste da caixa delimitadora, em que west_long é a longitude desse ponto e south_lat é a latitude. * east_long e north_lat representam o canto nordeste da caixa delimitadora, em que east_long é a longitude desse ponto e north_lat é a latitude. * A largura e a altura da caixa delimitadora devem ser menores que 25 mi. * A longitude está no intervalo de ±180. * A latitude está no intervalo de ±90. * Todas as coordenadas estão em graus decimais. * Os argumentos da regra devem estar entre colchetes, separados por espaço. Observação: Este operador não retornará correspondência em Retweets, pois os lugares dos Retweets estão anexados ao Post original. Também não corresponderá a lugares anexados ao Post original de um Quote Tweet.
profile_country:	Correspondência exata no campo “countryCode” do objeto “address” no enriquecimento Geo de Perfil. Usa um conjunto normalizado de códigos de país de duas letras, com base na especificação ISO-3166-1-alpha-2. Este operador é fornecido em vez de um operador para o campo “country” do objeto “address”, para ser conciso.
profile_region:	Corresponde ao campo “region” do objeto “address” no enriquecimento Geo de Perfil. Trata-se de uma correspondência exata de string completa. Não é necessário escapar caracteres com barra invertida. Por exemplo, ao corresponder algo com uma barra, use “one/two”, não “one/two”. Use aspas duplas para corresponder substrings que contenham espaços em branco ou pontuação.
profile_locality:	Corresponde ao campo “locality” do objeto “address” no enriquecimento Geo de Perfil. Trata-se de uma correspondência exata de string completa. Não é necessário escapar caracteres com barra invertida. Por exemplo, ao corresponder algo com uma barra, use “one/two”, não “one/two”. Use aspas duplas para corresponder substrings que contenham espaços em branco ou pontuação.

NOTA: Os operadores is: e has: não podem ser usados isoladamente ao utilizar a Search API; eles devem ser combinados com outra cláusula.Por exemplo: @XDeevelopers has:links


has:geo	Corresponde a Posts que possuem dados de localização geográfica específicos do Post fornecidos pelo X. Isso pode ser coordenadas “geo” de latitude-longitude, ou uma “location” na forma de um X “Place”, com nome de exibição correspondente, polígono geográfico e outros campos. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:profile_geo	Alias disponível: has:derived_user_geo Corresponde a Posts que possuem qualquer metadata de Profile Geo, independentemente do valor real. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:links	Este operador corresponde a Posts que contêm links no corpo da mensagem. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
is:retweet	Entrega apenas retweets explícitos que correspondem a uma regra. Também pode ser negado para excluir retweets que correspondem a uma regra da entrega e entregar apenas conteúdo original. Este operador procura apenas por Retweets verdadeiros, que usam a funcionalidade de retweet do X. Quote Tweets e Posts Modificados que não usam a funcionalidade de retweet do X não serão correspondidos por este operador. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
is:reply	Um operador para filtrar Posts com base em se são ou não respostas a Posts. Entrega apenas respostas explícitas que correspondem a uma regra. Também pode ser negado para excluir respostas que correspondem a uma regra da entrega. Observe que este operador está disponível para busca premium paga e Enterprise e não está disponível em ambientes de desenvolvimento Sandbox. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
is:quote	Entrega apenas Quote Tweets, ou Posts que referenciam outro Post, conforme identificado pelo “is_quote_status”:true nos payloads do Post. Também pode ser negado para excluir Quote Tweets. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
is:verified	Entrega apenas Posts onde o autor é “verificado” pelo X. Também pode ser negado para excluir Posts onde o autor é verificado. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:mentions	Corresponde a Posts que mencionam outro usuário do X. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:hashtags	Corresponde a Posts que contêm uma hashtag. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:media	Alias disponível: has:media_link Corresponde a Posts que contêm uma URL de mídia classificada pelo X. Por exemplo, pic.x.com. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:images	Corresponde a Posts que contêm uma URL de mídia classificada pelo X. Por exemplo, pic.x.com. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:videos	Alias disponível: has:video_link Corresponde a Posts que contêm vídeos nativos do X, enviados diretamente para o X. Isso não corresponderá a vídeos criados com Vine, Periscope, ou Posts com links para outros sites de hospedagem de vídeo. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.
has:symbols	Corresponde a Posts que contêm um símbolo cashtag (com um caractere ‘ $' inicial. Por exemplo,$ tag). Observe que este operador está disponível apenas nas APIs de busca `Enterprise`. Observação: Ao usar a Search API, este operador deve ser usado em conjunto com outros operadores que não incluam `is:` ou `has:`.

Visão geral do produto

O Full-archive Search no nível Enterprise foi lançado em agosto de 2015, e a versão no nível premium foi lançada em fevereiro de 2018. Esses produtos de busca permitem que os clientes acessem imediatamente qualquer Post disponível publicamente. Com o Full-archive Search, você envia uma única query e recebe uma resposta no formato RESTful clássico. O Full-archive Search implementa paginação de até 500 Posts por resposta e oferece um limite de taxa de até 60 solicitações por minuto (rpm) para premium e 120 rpm para Enterprise. Dadas essas características, o Full-archive Search pode ser usado para recuperar Posts rapidamente e em grande escala usando solicitações concorrentes. Diferentemente do Historical PowerTrack, cujo acervo é baseado em um conjunto de arquivos flat de Post em disco, o acervo de Posts do Full-archive Search é semelhante a um banco de dados on-line. Como em todos os bancos de dados, ele permite fazer consultas sobre seu conteúdo. Ele também usa um índice para possibilitar a recuperação de dados de alto desempenho. Com os endpoints do Full-archive Search, a linguagem de consulta é composta por PowerTrack Operators, e cada um desses Operators corresponde a um atributo JSON de Post que é indexado. Além disso, assim como no Historical PowerTrack, há atributos de Post que refletem o estado atual no momento em que uma query é feita. Por exemplo, se você estiver usando a Search API para acessar hoje um Post publicado em 2010, a descrição do perfil do usuário, a localização “home” da conta, o nome de exibição e as metrics do Post para contagens de likes e Retweets serão atualizados para os valores de hoje e não para os que existiam em 2010.

Cronogramas de metadata

Abaixo está um cronograma de quando os operadores do endpoint de Full-archive search passam a fazer correspondência. Em alguns casos, a correspondência por operadores começou bem depois que uma “convenção de comunicação” se tornou comum no X. Por exemplo, @Replies surgiu como uma convenção de usuário em 2006, mas só se tornou um objeto de primeira classe ou evento com JSON “de suporte” no início de 2007. Assim, fazer correspondência com @Replies em 2006 exige examinar o corpo do Post, em vez de depender dos operadores PowerTrack to: e in_reply_to_status_id:. Os detalhes fornecidos aqui foram gerados usando Full-Archive Search (resultado de centenas de buscas). Este cronograma não é 100% completo ou preciso. Se você identificar outra “data de nascimento” de filtragem/metadata fundamental para o seu caso de uso, por favor, avise-nos. Observe que o índice de Search subjacente pode ser reconstruído. Consequentemente, esses detalhes do cronograma estão sujeitos a alterações.

2006

26 de março - lang:. Um exemplo de metadata de Post sendo preenchida retroativamente durante a geração do índice de busca.
13 de julho - has:mentions passa a ter correspondência.
6 de outubro - has:symbols. $cashtags (ou símbolos) para discutir símbolos de ações só se tornam comuns no início de 2009. Até então, a maioria dos usos provavelmente era gíria (por exemplo,$ slang).
26 de outubro - has:links passa a ter correspondência.
23 de novembro - has:hashtags passa a ter correspondência.

2007

30 de janeiro - Primeira @reply de primeira classe (in_reply_to_user_id); reply_to_status_id: passa a corresponder.
23 de agosto - Hashtags surgem como uma convenção comum para organizar tópicos e conversas. Primeiro uso real uma semana depois.

2009

15 de maio - is:retweet. Observe que este operador começa a corresponder com o lançamento beta de Retweets oficiais e seu padrão “Via @”. Durante esse período beta, o verbo do Post é “post” e o Post original não é incluído no payload.
13 de agosto - A versão final dos Retweets oficiais é lançada com o padrão “RT @”, um verbo definido como “share” e o atributo “retweet_status” contendo o Post original (assim, aproximadamente dobrando o tamanho do payload JSON).

2010

6 de março – os Operadores geográficos has:geo, bounding_box: e point_radius: passam a fazer correspondência.
28 de agosto – has:videos (Até fevereiro de 2015, este Operador fazia correspondência com Posts que continham links para determinados sites de hospedagem de vídeo, como youtube.com, vimeo.com e vivo.com).

2011

20 de julho - has:media e has:images passam a corresponder. Fotos nativas anunciadas oficialmente em 9 de agosto de 2010.

2014

3 de dezembro — (aproximadamente) Alguns Enhanced URL metadata com title e descrição em HTML começam a aparecer nos payloads. A metadata aprimorada passou a se consolidar em maio de 2016.

2015

10 de fevereiro - has:videos corresponde a vídeos “nativos” do X.
17 de fevereiro - Os operadores de Profile Geo has:profile_geo, profile_country:, profile_region:, profile_locality: passam a ter correspondência.
17 de fevereiro - Os operadores de geolocalização de Post place_country: e place: passam a ter correspondência.

2016

1º de maio - metadados de URL aprimorados mais amplamente disponíveis e anunciados oficialmente como parte do lançamento do Gnip 2.0 em agosto de 2016. Sem operadores associados para esses metadados nas APIs de Search.

2017

22 de fevereiro - Metadata de enquete ficam disponíveis em formato nativo enriquecido. Não há Operadores associados para essas metadata.

2022

27 de setembro - Todos os Objetos Post criados desde essa data têm metadados de Post editado disponíveis. Todos os endpoints Enterprise que fornecem Objetos Post foram atualizados para fornecer esses metadados a partir dessa data. Os metadados de edição fornecidos incluem os objetos edit_history e edit_controls. Esses metadados não serão retornados para Posts criados antes de 27 de setembro de 2022. Atualmente, não há Operadores Enterprise disponíveis que correspondam a esses metadados. Para saber mais sobre os metadados de edição de Post, confira a página Fundamentos de edição de Posts.

2022

29 de setembro – Todos os Objetos Post criados desde essa data têm metadados de Post editado disponíveis. Todos os endpoints Enterprise que fornecem Objetos Post foram atualizados para fornecer esses metadados a partir dessa data. Os metadados de edição fornecidos incluem os objetos edit_history e edit_controls. Esses metadados não serão retornados para Posts criados antes de 27 de setembro de 2022. Atualmente, não há Operadores Enterprise disponíveis que correspondam a esses metadados. Para saber mais sobre os metadados de Edit Post, confira a página Edit Posts fundamentals.

Dicas de filtragem

Diante de todas as informações de timeline acima, fica claro que há muitos detalhes a considerar ao escrever filtros das Search APIs. Há dois pontos principais a considerar:

Alguns metadata têm datas de “nascimento”, portanto os filtros podem resultar em falsos negativos. Essas buscas incluem operadores que dependem de metadata que não existiam durante todo ou parte do período pesquisado. Por exemplo, se você estiver procurando Posts com o operador has:images, não haverá correspondências para períodos anteriores a julho de 2011. Isso ocorre porque esse operador corresponde a fotos nativas (anexadas a um Post usando a interface do usuário do X). Para um conjunto de dados mais completo de Posts de compartilhamento de fotos, filtros para antes de julho de 2011 precisariam conter cláusulas de regra que correspondam a URLs comuns de hospedagem de fotos.
Alguns metadata foram preenchidos retroativamente com informações de um período posterior ao momento em que o Post foi publicado.

Há vários tipos de atributos comumente priorizados ao criar consultas PowerTrack:

Perfis do X
Posts originais ou compartilhados
Classificação de idioma do Post
Georreferenciamento de Posts
Mídia de links compartilhados

Alguns desses têm comportamento específico do produto, enquanto outros têm comportamento idêntico. Veja abaixo para mais detalhes.

Perfis no X

As Search APIs fornecem Posts históricos com os dados de perfil do usuário conforme estão no momento da recuperação. Se você solicitar um Post de 2014, os metadata do perfil do usuário refletirão como ele existe no momento da query.

Posts originais e Retweets

O operador PowerTrack _is:retweet_ permite incluir ou excluir Retweets. Usuários desse operador precisam adotar duas estratégias para identificar (ou não) Retweets em dados anteriores a agosto de 2009. Antes de agosto de 2009, é necessário verificar a própria mensagem do Post, usando correspondência de frase exata, para achar ocorrências do padrão “@RT ” (na verdade, se você estiver filtrando Retweets entre maio e agosto de 2009, o padrão “Via @” também deve ser incluído). Para períodos após agosto de 2009, o operador is:retweet está disponível.

Classificações de idioma de Post

Para filtrar pela classificação de idioma de um Post, os produtos históricos do X funcionam de forma bastante diferente. Quando o arquivo de Search foi criado, todos os Posts foram retroativamente preenchidos com a classificação de idioma do X. Portanto, o operador lang: está disponível para todo o arquivo de Posts.

Georreferenciamento de Posts

Há três maneiras principais de georreferenciar Posts:

Referências geográficas na mensagem do Post. Fazer correspondência com referências geográficas na mensagem do Post, embora muitas vezes seja o método mais desafiador por depender de conhecimento local, é uma opção para todo o arquivo de Posts. Aqui está um exemplo de correspondência georreferenciada de 2006 para a região de São Francisco com base em um filtro “golden gate”.
Posts com geotag definidos pelo usuário. Com as APIs de busca, a capacidade de começar a corresponder Posts usando alguns Operadores de Geo começou em março de 2010 e, com outros, em fevereiro de 2015:
- 6 de março de 2010: has:geo, bounding_box: e point_radius:
- 17 de fevereiro de 2015: place_country: e place:
Localização “home” do perfil da conta definida pelo usuário. Operadores de Geo de Perfil estão disponíveis tanto no Historical PowerTrack quanto nas Search APIs. Com as Search APIs, esses metadados de Geo de Perfil estão disponíveis a partir de fevereiro de 2015. Para Posts publicados antes de os metadados de Geo de Perfil estarem disponíveis, o operador bio_location: está disponível e pode ser usado para corresponder a entradas de usuário não normalizadas.

Links e mídias compartilhados

Em março de 2012, foi introduzido o enriquecimento de URLs expandidas. Antes disso, os payloads de Post incluíam apenas a URL informada pelo usuário. Assim, se o usuário incluísse uma URL encurtada, poderia ser difícil fazer a correspondência com as URLs (expandidas) de interesse. Com as APIs de Search, esses metadados estão disponíveis a partir de março de 2012. Em julho de 2016, foi introduzido o enriquecimento de URLs aprimoradas. Essa versão fornece o título e a descrição HTML de um site no payload do Post, juntamente com Operators para correspondência. Esses metadados começam a aparecer em dezembro de 2014. Em setembro de 2016, a X introduziu “anexos nativos”, nos quais um link compartilhado ao final não é contabilizado no limite de 140 caracteres do Post. Ambos os enriquecimentos de URL ainda se aplicam a esses links compartilhados. Confira quando os Search Operators relacionados passaram a ter correspondência:

26 de outubro de 2006 - has:links
20 de julho de 2011 - has:images e has:media
agosto de 2011 - url: com o Expanded URLs enrichment. Já em setembro de 2006, (url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube) faz correspondência com http://x.com/Adam/statuses/16602, mesmo sem metadados urls[] em twitter_entities e nos objetos gnip. “youtube.com” é um exemplo de conteúdo de mensagem que, sem quaisquer metadados urls[], corresponde a url:youtube.
10 de fevereiro de 2015 - has:videos para vídeos nativos. Entre 2010/08/28 e 2015/02/10, esse Operator corresponde a Posts com links para sites selecionados de hospedagem de vídeo, como youtube.com, vimeo.com e vivo.com.
1º de maio de 2016 - url_title: e url_description:, com base no Enhanced URLs enrichment, disponibilizados de forma geral. Os primeiros metadados de Enhanced URL começaram a aparecer em dezembro de 2014.

Perguntas frequentes (FAQ)

Perguntas gerais sobre a API de Post de pesquisa

O número de Posts que recebo com o endpoint data não corresponde ao número de Posts identificados pelo endpoint de contagem. Por que isso acontece?

Há uma diferença conhecida entre os resultados fornecidos pelo endpoint de contagens e pelo endpoint de data. Você pode observar uma discrepância nos seus resultados porque o endpoint de contagens é pré-compliance (ou seja, não considera itens como Posts excluídos, scrub_geo etc.), enquanto o endpoint de data está em conformidade no momento da entrega e leva em conta todos os eventos de compliance.

Não recebi um Post que deveria corresponder à minha query. Por quê?

Há alguns motivos diferentes pelos quais isso pode ter acontecido, incluindo

o Post que você esperava ver é de uma conta protegida
o endpoint data considera todos os eventos de conformidade (o que significa que Posts excluídos, geos removidos, etc. não serão incluídos na resposta).

Minha query correspondeu a um Post, mas inclui uma palavra‑chave que eu neguei. Por que isso está acontecendo?

Isso provavelmente ocorre devido ao uso incorreto de nossas regras premium e de filtragem. Consulte nossa documentação aqui e certifique-se de entender as restrições relacionadas à criação de regras.

Existem bibliotecas que eu possa usar para começar a utilizar as APIs de Search Post?

Sim, existem, incluindo:

Tweepy - bom para usar o produto padrão de busca/Posts (Python)
X API - bom para usar as APIs padrão de Search Post (Python)
Search Posts Python e Search Posts Ruby - duas boas ferramentas que podem ser usadas com as APIs de Search Post do Enterprise (e v2!)

Todas as bibliotecas que oferecemos suporte diretamente podem ser encontradas na nossa página do GitHub do xdevplatform: https://github.com/xdevplatform.Há outras bibliotecas de terceiros que também podem ser úteis; no entanto, observe que algumas delas podem não funcionar com nossos produtos premium e Enterprise.

Eu posso receber um volume de Posts menor do que o valor que defini como `maxResults` na minha solicitação ao endpoint de data?

Sim. Nosso endpoint data faz paginação com base no maxResults especificado ou após 30 dias.Por exemplo, se você tiver 800 Posts em um período de 30 dias, será necessário fazer duas solicitações para obter todos os resultados, pois o número máximo de Posts que pode ser retornado por solicitação é 500 (maxResults). E se você tiver apenas 400 Posts no primeiro mês e 100 Posts no segundo, também será necessário usar duas solicitações para obter o conjunto completo de resultados, porque a paginação ocorre após um período de 30 dias, mesmo que a primeira solicitação retorne menos Posts do que o maxResults especificado.

Em que ordem os Posts correspondentes são retornados?

Posts são retornados em ordem cronológica inversa. Por exemplo, a primeira página de resultados mostrará os Posts mais recentes que correspondem à query; a paginação continuará até que as datas de publicação dos resultados cheguem ao fromDate solicitado inicialmente.

Como as edições de Posts impactam meu uso e faturamento?

Somente o Post original será contabilizado para fins de cobrança. Quaisquer edições subsequentes serão ignoradas e não contarão para a sua contagem geral de atividade.Enterprise

Estou interessado em saber mais sobre os preços da API de Search Post para Enterprise e em solicitar essa oferta. Como posso fazer isso?

Nossas soluções Enterprise são personalizadas, com preços previsíveis, para atender às necessidades da sua empresa. Solicite mais informações aqui.

Como posso criar um conjunto de regras que atenda ao meu caso de uso?

Consulte nossa documentação das APIs de Search Post do Enterprise aqui
Informações úteis sobre regras e filtragem podem ser encontradas aqui
Informações úteis sobre o uso do endpoint data podem ser encontradas aqui
Informações úteis sobre o uso do endpoint counts podem ser encontradas aqui
Uma lista de operadores disponíveis pode ser encontrada aqui

Excedi meus limites/cotas de solicitações do mês, mas preciso acessar mais data — o que posso fazer?

Entre em contato com seu gerente de conta na X, que poderá ajudar você com isso.

Guia de solução de problemas de erros

Código 404 - Não encontrado

Verifique se você está usando os parâmetros corretos para cada endpoint (por exemplo, o campo buckets só pode ser usado com o endpoint de contagens, não com o endpoint de data)
Verifique novamente se os campos :product, :account_name e :label estão corretos. Você pode encontrar o seu :label no GNIP Console (apenas para clientes Enterprise).

Referência da API

APIs de busca Enterprise

Existem duas APIs de busca Enterprise:

30-Day Search API - fornece Tweets publicados nos últimos 30 dias.
Full-Archive Search API - fornece Tweets desde 2006, começando pelo primeiro Tweet publicado em março de 2006.

Essas APIs de busca compartilham um design comum e a documentação abaixo se aplica a ambas. Observe que, para Tweets criados a partir de 29 de setembro de 2022, os objetos de Tweet incluirão metadata de edição de Tweet que descreve seu histórico de edições. Consulte a página de fundamentos “Edit Tweets” para mais detalhes. Abaixo você encontrará detalhes importantes necessários para integrar com as APIs de busca Enterprise:

Métodos para solicitar dados e contagens de Tweets
Autenticação
Paginação
Parâmetros de requisição da API e exemplos de requisições
Cargas JSON de resposta da API e exemplos de respostas
Códigos de resposta HTTP

As APIs Enterprise fornecem acesso de baixa latência, alta fidelidade e baseado em query ao arquivo de Tweets. A única diferença entre as duas APIs é o intervalo de tempo que você pode pesquisar: os 30 dias anteriores ou desde 2006. Os intervalos de tempo podem ser especificados com granularidade de minutos. Os dados de Tweets são servidos em ordem cronológica inversa, começando pelo Tweet mais recente que corresponde à sua query. Os Tweets ficam disponíveis na API de busca aproximadamente 30 segundos após serem publicados.

Métodos

O URI base para a pesquisa Enterprise é https://gnip-api.x.com/search/.

Método	Descrição
POST /search/:product/accounts/:account_name/:label	Recupera Tweets dos últimos 30 dias que correspondem à regra PowerTrack especificada.
POST /search/:product/accounts/:account_name/:label/counts	Recupera o número de Tweets dos últimos 30 dias que correspondem à regra PowerTrack especificada.

Onde:

:product indica o endpoint de pesquisa para o qual você está fazendo solicitações, 30day ou fullarchive.
:account_name é o nome (diferencia maiúsculas de minúsculas) associado à sua conta, conforme exibido em console.gnip.com
:label é o rótulo (diferencia maiúsculas de minúsculas) associado ao seu endpoint de pesquisa, conforme exibido em console.gnip.com

Por exemplo, se a conta TwitterDev tiver o produto de pesquisa de 30 dias com o rótulo “prod” (abreviação de produção), os endpoints de pesquisa seriam:

Endpoint de dados: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json
Endpoint de contagens: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json

Seu endpoint completo da API de pesquisa Enterprise é exibido em https://console.gnip.com. A seguir, há vários exemplos de solicitações usando um utilitário HTTP simples chamado curl. Esses exemplos usam URLs com :product, :account_name e :label. Para usar esses exemplos, certifique-se de atualizar as URLs com seus dados.

Autenticação

Todas as solicitações às APIs de pesquisa Enterprise devem usar HTTP Basic Authentication, composta por uma combinação válida de endereço de e-mail e senha utilizada para acessar sua conta em https://console.gnip.com. As credenciais devem ser enviadas no cabeçalho Authorization em cada solicitação.

Comportamento de solicitação/resposta

Usando os parâmetros fromDate e toDate, você pode solicitar qualquer período que a API suporte. A 30-Day search API fornece Tweets dos últimos 31 dias (mesmo sendo chamada de ‘30-Day’ API, ela disponibiliza 31 dias para permitir que os usuários façam solicitações de mês completo). A Full-Archive search API fornece Tweets desde o primeiro Tweet (21 de março de 2006). No entanto, uma única resposta será limitada ao menor valor entre o maxResults que você especificar ou 31 dias. Se os dados correspondentes ou o seu intervalo de tempo excederem o maxResults especificado ou 31 dias, você receberá um token ‘next’ que deve ser usado para paginar pelo restante do intervalo de tempo solicitado. Por exemplo, suponha que você esteja usando a Full-Archive search e queira todos os Tweets que correspondam à sua query de 1º de janeiro de 2017 a 30 de junho de 2017. Você especificará esse período completo de seis meses na sua solicitação usando os parâmetros fromDate e toDate. A search API responderá com a primeira ‘página’ de Tweets, com a quantidade de Tweets correspondente ao seu parâmetro maxResults (que, por padrão, é 100). Supondo que haja mais Tweets (e muito provavelmente haverá), a API também fornecerá um token ‘next’ que permite fazer uma solicitação para a próxima ‘página’ de data. Esse processo se repete até que a API não retorne um token ‘next’. Consulte a próxima seção para mais detalhes.

Paginação

Ao fazer solicitações de dados e de contagem, é provável que haja mais informações do que as que podem ser retornadas em uma única resposta. Nesses casos, a resposta incluirá um token “next”. O token “next” é fornecido como um atributo JSON no nível raiz. Sempre que um token “next” for fornecido, há dados adicionais a serem recuperados, portanto, você precisará continuar fazendo solicitações à API. Observação: O comportamento do token “next” difere ligeiramente entre solicitações de dados e de contagem, e ambos são descritos abaixo, com respostas de exemplo fornecidas na seção API Reference.

Paginação de dados

As solicitações de dados provavelmente gerarão mais resultados do que cabem em uma única resposta. Cada solicitação inclui um parâmetro que define o número máximo de Tweets a retornar por requisição. Esse parâmetro maxResults tem valor padrão de 100 e pode ser configurado entre 10 e 500. Se sua query corresponder a mais Tweets do que o valor de ‘maxResults’ usado na solicitação, a resposta incluirá um token ‘next’ (como um atributo JSON no nível raiz). Esse token ‘next’ é usado na solicitação subsequente para recuperar a próxima parte dos Tweets correspondentes a essa query (ou seja, a próxima “página”). Tokens ‘next’ continuarão sendo fornecidos até que você chegue à última “página” de resultados para essa query, quando nenhum token ‘next’ for retornado. Para solicitar a próxima “página” de dados, você deve repetir exatamente a mesma query da solicitação original, incluindo os parâmetros query, toDate e fromDate, se usados, e também incluir um parâmetro de solicitação ‘next’ definido com o valor retornado na resposta anterior. Isso pode ser feito com uma solicitação GET ou POST. No entanto, o parâmetro ‘next’ deve ser codificado na URL em solicitações GET. Você pode continuar a enviar o elemento ‘next’ da sua query anterior até receber todos os Tweets do período coberto por ela. Quando você receber uma resposta que não inclua um elemento ‘next’, isso significa que você chegou à última página e não há dados adicionais disponíveis para a query e o intervalo de tempo especificados.

Paginação de contagens

O endpoint ‘counts’ fornece volumes de Tweet associados a uma query em base diária, horária ou por minuto. O endpoint da API ‘counts’ retornará um array de contagens com carimbo de data/hora para, no máximo, um payload de 31 dias de contagens. Se você solicitar mais de 31 dias de contagens, será fornecido um token ‘next’. Assim como com os tokens ‘next’ de data, você deve fazer exatamente a mesma query que a original e também incluir um parâmetro de requisição ‘next’ definido com o valor da resposta anterior. Além de solicitar mais de 31 dias de contagens, há outro cenário em que um token ‘next’ é fornecido. Para queries de maior volume, existe a possibilidade de que a geração das contagens demore o suficiente para acionar um timeout de resposta. Quando isso ocorre, você receberá menos de 31 dias de contagens, mas será fornecido um token ‘next’ para continuar fazendo solicitações e obter todo o payload de contagens. Importante: Timeouts emitirão apenas “buckets” completos — assim, 2,5 dias resultariam em 2 “buckets” de dia completos.

Notas adicionais

Ao usar fromDate ou toDate em uma solicitação de busca, você receberá apenas resultados dentro do intervalo de tempo especificado. Quando chegar ao último grupo de resultados desse intervalo, você não receberá um token ‘next’.
O elemento ‘next’ pode ser usado com qualquer valor de maxResults entre 10 e 500 (valor padrão de 100). O maxResults determina quantos Tweets são retornados em cada resposta, mas não impede que você eventualmente obtenha todos os resultados.
O elemento ‘next’ não expira. Várias solicitações usando a mesma query ‘next’ receberão os mesmos resultados, independentemente de quando a solicitação for feita.
Ao paginar os resultados usando o parâmetro ‘next’, você pode encontrar duplicatas nos limites da query. Sua App deve ser tolerante a isso.

endpoint de data

POST /search/:product/:label

Padrão do endpoint:

Este endpoint retorna dados para a query e o período de tempo especificados. Se um período não for especificado, os parâmetros de tempo terão como padrão os últimos 30 dias. Observação: Essa funcionalidade também pode ser obtida usando uma solicitação GET, em vez de POST, codificando os parâmetros descritos abaixo na URL.

Parâmetros da solicitação de dados

Parâmetros	Descrição	Obrigatório	Valor de exemplo
query	Equivalente a uma regra do PowerTrack, com até 2.048 caracteres (sem limite para o número de cláusulas positivas e negativas). Este parâmetro deve incluir TODAS as partes da regra do PowerTrack, incluindo todos os operadores; partes da regra não devem ser separadas em outros parâmetros da query. Observação: Nem todos os operadores do PowerTrack são compatíveis. Os operadores compatíveis estão listados AQUI.	Sim	(snow OR cold OR blizzard) weather
tag	As tags podem ser usadas para segmentar regras e seus dados correspondentes em diferentes grupos lógicos. Se uma tag de regra for fornecida, ela será incluída no atributo ‘matching_rules’. Recomenda-se atribuir UUIDs específicos de regra às tags e manter os mapeamentos desejados no lado do cliente.	Não	8HYG54ZGTU
fromDate	O carimbo de data/hora UTC mais antigo (até 21/3/2006 com a pesquisa Full-Archive) a partir do qual os Tweets serão fornecidos. O carimbo tem granularidade de minuto e é inclusivo (isto é, 12:00 inclui o minuto 00). Especificado: Usar apenas fromDate, sem o parâmetro toDate, retornará resultados para a query retrocedendo no tempo a partir de now( ) até fromDate. Não especificado: Se fromDate não for especificado, a API retornará todos os resultados dos 30 dias anteriores a now( ) ou a toDate (se especificado). Se nem fromDate nem toDate forem usados, a API retornará todos os resultados dos 30 dias mais recentes, começando no momento da solicitação, retrocedendo.	Não	201207220000
toDate	O carimbo de data/hora UTC mais recente até o qual os Tweets serão fornecidos. O carimbo tem granularidade de minuto e não é inclusivo (isto é, 11:59 não inclui o 59º minuto da hora). Especificado: Usar apenas toDate, sem o parâmetro fromDate, retornará os 30 dias mais recentes de dados anteriores a toDate. Não especificado: Se toDate não for especificado, a API retornará todos os resultados a partir de now( ) para a query, retrocedendo no tempo até fromDate. Se nem fromDate nem toDate forem usados, a API retornará todos os resultados de todo o índice de 30 dias, começando no momento da solicitação, retrocedendo.	Não	201208220000
maxResults	O número máximo de resultados de pesquisa a serem retornados por uma solicitação. Um valor entre 10 e o limite do sistema (atualmente 500). Por padrão, a resposta retornará 100 resultados.	Não	500
next	Este parâmetro é usado para obter a próxima “página” de resultados, conforme descrito AQUI. O valor usado com o parâmetro é extraído diretamente da resposta fornecida pela API e não deve ser modificado.	Não	NTcxODIyMDMyODMwMjU1MTA0

Detalhes adicionais


Período disponível	30-Day: últimos 31 dias Full-Archive: 21 de março de 2006 - presente
Formato de query	Equivalente a uma regra do PowerTrack, com até 2.048 caracteres (sem limites para o número de cláusulas positivas e negativas). Observação: Nem todos os operadores do PowerTrack são compatíveis. Consulte Available operators para a lista de operadores compatíveis.
Limite de taxa	Os parceiros estarão sujeitos a limites com granularidade de minuto e segundo. O limite por minuto varia por parceiro, conforme especificado em contrato. No entanto, esses limites por minuto não devem ser usados em um único pico. Independentemente do seu limite por minuto, todos os parceiros estarão limitados a, no máximo, 20 solicitações por segundo, agregadas em todas as solicitações de data e/ou de contagem.
Conformidade	Todos os data entregues pela Full-Archive Search API estão em conformidade no momento da entrega.
Disponibilidade em tempo real	Os data ficam disponíveis no índice em até 30 segundos após a geração na plataforma X

Exemplos de solicitações e respostas de dados

Exemplo de requisição POST

Os parâmetros de uma requisição POST são enviados em um corpo no formato JSON, como mostrado abaixo.
Todas as partes da regra do PowerTrack que está sendo consultada (por exemplo, palavras-chave e outros operadores, como bounding_box:) devem ser colocadas no parâmetro ‘query’.
Não separe partes da regra em parâmetros distintos na URL da query.

Aqui está um exemplo de comando POST (usando cURL) para fazer uma requisição inicial de dados:

    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 a resposta de dados da API incluir um token ‘next’, abaixo está uma solicitação subsequente que replica a solicitação original, com o parâmetro ‘next’ definido para o token fornecido:

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

Exemplo de solicitação GET

Os parâmetros de uma solicitação GET são codificados na URL, usando a codificação padrão de URL.
Todas as partes da regra do PowerTrack que estão sendo consultadas (por exemplo, palavras-chave, outros operadores como bounding_box:) devem ser colocadas no parâmetro ‘query’.
Não divida partes da regra em parâmetros separados na URL da consulta.

Aqui está um exemplo de comando GET (usando cURL) para fazer uma solicitação inicial de 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"

Exemplos de respostas de dados

Observe que, para Tweets criados a partir de 29 de setembro de 2022, os objetos de Tweet incluirão metadados de edição de Tweet que descrevem seu histórico de edições. Consulte a página de fundamentos “Edit Tweets” para mais detalhes. Abaixo está um exemplo de resposta para uma consulta de dados. Este exemplo pressupõe que havia mais do que ‘maxResults’ Tweets disponíveis, portanto, um token ‘next’ é fornecido para solicitações subsequentes. Se ‘maxResults’ ou menos Tweets estiverem associados à sua query, nenhum token ‘next’ será incluído na resposta. O valor do elemento ‘next’ mudará a cada query e deve ser tratado como uma string opaca. O elemento ‘next’ terá a seguinte aparência no corpo da resposta:

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

A resposta a uma solicitação subsequente pode ser semelhante ao exemplo a seguir (observe os novos Tweets e o valor diferente de “next”):

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

Você pode continuar a passar o elemento ‘next’ da sua query anterior até receber todos os Tweets do período coberto pela sua query. Quando você receber uma resposta que não inclua um elemento ‘next’, isso significa que você chegou à última página e não há dados adicionais disponíveis no seu intervalo de tempo.

endpoint de contagem

/search/:stream/counts

Padrão do endpoint:

/search/fullarchive/accounts/:account_name/:label/counts.json Este endpoint retorna contagens (volumes de dados) para a query especificada. Se nenhum período de tempo for informado, os parâmetros de tempo terão como padrão os últimos 30 dias. Os volumes de dados são retornados como um array com carimbo de data/hora em base diária, horária (padrão) ou por minuto. Observação: Essa funcionalidade também pode ser obtida usando uma requisição GET, em vez de POST, codificando os parâmetros descritos abaixo na URL.

Parâmetros da solicitação de contagens

Parâmetros	Descrição	Obrigatório	Valor de exemplo
query	Equivale a uma regra do PowerTrack, com até 2.048 caracteres (sem limites para o número de cláusulas positivas e negativas). Este parâmetro deve incluir TODAS as partes da regra do PowerTrack, incluindo todos os operadores; partes da regra não devem ser separadas em outros parâmetros da query. Observação: Nem todos os operadores do PowerTrack são compatíveis. Consulte Operadores disponíveis para ver a lista de operadores compatíveis.	Sim	(snow OR cold OR blizzard) weather
fromDate	O carimbo de data/hora em UTC mais antigo (desde 21/03/2006) a partir do qual os Tweets serão fornecidos. O carimbo de data/hora tem granularidade de minuto e é inclusivo (isto é, 12:00 inclui o minuto 00). Especificado: Ao usar apenas fromDate, sem o parâmetro toDate, a API fornecerá dados de contagem (volumes de dados) para a query retrocedendo no tempo, do momento atual até o fromDate. Se o fromDate for anterior a 31 dias a partir de agora, você receberá um next token para paginar sua solicitação. Não especificado: Se um fromDate não for especificado, a API fornecerá contagens (volumes de dados) para os 30 dias anteriores ao momento atual ou ao toDate (se especificado). Se nem o parâmetro fromDate nem o toDate for usado, a API fornecerá contagens (volumes de dados) para os 30 dias mais recentes, a partir do momento da solicitação, retrocedendo.	Não	201207220000
toDate	O carimbo de data/hora em UTC mais recente até o qual os Tweets serão fornecidos. O carimbo de data/hora tem granularidade de minuto e não é inclusivo (isto é, 11:59 não inclui o 59º minuto da hora). Especificado: Ao usar apenas toDate, sem o parâmetro fromDate, serão fornecidas as contagens (volumes de dados) mais recentes para os 30 dias anteriores ao toDate. Não especificado: Se um toDate não for especificado, a API fornecerá contagens (volumes de dados) para a query retrocedendo no tempo até o fromDate. Se o fromDate for mais de 31 dias a partir de agora, você receberá um next token para paginar sua solicitação. Se nem o parâmetro fromDate nem o toDate for usado, a API fornecerá contagens (volumes de dados) para os 30 dias mais recentes, a partir do momento da solicitação, retrocedendo.	Não	201208220000
bucket	A unidade de tempo para a qual os dados de contagem serão fornecidos. As contagens podem ser retornadas para cada dia, hora ou minuto no período solicitado. Por padrão, serão fornecidas contagens por hora. Opções: ‘day’, ‘hour’, ‘minute’	Não	minute
next	Este parâmetro é usado para obter a próxima ‘página’ de resultados, conforme descrito AQUI. O valor usado com o parâmetro é obtido diretamente da resposta fornecida pela API e não deve ser modificado.	Não	NTcxODIyMDMyODMwMjU1MTA0

Detalhes adicionais


Período disponível	30-Day: últimos 31 dias Full-Archive: 21 de março de 2006 - presente
Formato de query	Equivalente a uma regra PowerTrack, com até 2.048 caracteres. Observação: Nem todos os operadores PowerTrack são compatíveis. Consulte Available operators para a lista de operadores compatíveis.
Limite de taxa	Os parceiros estarão sujeitos a limite de taxa com granularidade de minuto e segundo. O limite por minuto variará por parceiro, conforme especificado no seu contrato. No entanto, esses limites por minuto não devem ser utilizados em um único pico. Independentemente do seu limite por minuto, todos os parceiros estarão limitados a, no máximo, 20 solicitações por segundo, agregadas em todas as solicitações para data e/ou contagens.
Precisão da contagem	As contagens fornecidas por este endpoint refletem o número de Tweets que ocorreram e não consideram eventos de conformidade posteriores (exclusões, scrub geos). Alguns Tweets contabilizados podem não estar disponíveis via endpoint de data devido a ações de conformidade do usuário.

Exemplos de solicitações e respostas de contagem

Exemplo de solicitação POST

Os parâmetros de uma solicitação POST são enviados em um corpo no formato JSON, conforme mostrado abaixo.
Todos os elementos da regra do PowerTrack que estão sendo consultados (por exemplo, palavras-chave e outros operadores, como bounding_box:) devem ser colocados no parâmetro ‘query’.
Não separe partes da regra como parâmetros distintos na URL da query.

A seguir, um exemplo de comando POST (usando cURL) para fazer uma solicitação inicial de contagens:

    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 a resposta de contagens da API incluir um token ‘next’, abaixo está uma solicitação subsequente que replica a solicitação original, com o parâmetro ‘next’ definido para o token fornecido:

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

Exemplo de solicitação GET

Os parâmetros de uma solicitação GET são codificados na URL, usando a codificação padrão de URL
Todas as partes da regra do PowerTrack que estão sendo consultadas (por exemplo, palavras-chave, outros operadores como bounding_box:) devem ser colocadas no parâmetro ‘query’
Não separe partes da regra em parâmetros distintos na URL de consulta

Aqui está um exemplo de comando GET (usando cURL) para fazer uma solicitação inicial de contagem:

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

Exemplos de respostas de contagem

Abaixo está um exemplo de resposta para uma query de contagem (volume de dados). Este exemplo de resposta inclui um token ‘next’, o que significa que a solicitação de contagem abrangia mais de 31 dias ou que a query enviada tinha um volume suficientemente grande associado a ela para gerar uma resposta parcial. O valor do elemento ‘next’ mudará a cada query e deve ser tratado como uma string opaca. O elemento ‘next’ terá a seguinte aparência no corpo da resposta:

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

A resposta a uma solicitação subsequente pode ser semelhante ao seguinte (observe a nova linha do tempo de contagens e o valor diferente de “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"
        }
    }

Você pode continuar a enviar o elemento ‘next’ da sua query anterior até receber todas as contagens do período da query. Quando receber uma resposta que não inclui o elemento ‘next’, isso significa que você chegou à última página e não há contagens adicionais disponíveis no seu intervalo de tempo.

Códigos de resposta HTTP

Status	Texto	Descrição
200	OK	A solicitação foi bem-sucedida. A resposta JSON será semelhante ao seguinte:
400	Bad Request	Geralmente, essa resposta ocorre devido à presença de JSON inválido na solicitação ou quando a solicitação não envia nenhum payload JSON.
401	Unauthorized	A autenticação HTTP falhou devido a credenciais inválidas. Faça login em console.gnip.com com suas credenciais para garantir que você as esteja usando corretamente na solicitação.
404	Not Found	O recurso não foi encontrado na URL para a qual a solicitação foi enviada, provavelmente porque uma URL incorreta foi usada.
422	Unprocessable Entity	Retornado devido a parâmetros inválidos na query — por exemplo, regras PowerTrack inválidas.
429	Unknown Code	Seu App excedeu o limite de solicitações de conexão. A mensagem JSON correspondente será semelhante ao seguinte:
500	Internal Server Error	Ocorreu um erro no servidor. Tente sua solicitação novamente usando um padrão de recuo exponencial.
502	Proxy Error	Ocorreu um erro no servidor. Tente sua solicitação novamente usando um padrão de recuo exponencial.
503	Service Unavailable	Ocorreu um erro no servidor. Tente sua solicitação novamente usando um padrão de recuo exponencial.

Visão geral

Posts

users

Mensagens diretas

Likes

List

Spaces

Comunidades

Notas da Comunidade

Tendências

Mídia

Uso

Conexões do stream

Conformidade

Enterprise v2

Likes Streams

GNIP 2.0

​Visão geral

​Tipos de solicitação

​Solicitações de pesquisa (data)

​Solicitações de contagem (Contagem de Posts)

​Operadores disponíveis

​Disponibilidade de dados / datas importantes

​Atualizações de dados e mutabilidade

​Solicitações single-thread vs. multi-thread

​Lógica de novas tentativas

​Introdução rápida

​Introdução à enterprise Search Posts: 30-Day API

​Acessando o endpoint de data

​Payload de resposta do endpoint de dados

​Acessando o endpoint de contagens

​Payload de resposta do endpoint Counts

Artigos relacionados

​Introdução ao uso da Enterprise Search Posts: Full-Archive API

​Acessando o endpoint de data

Payload de resposta do endpoint de dados

​Acessando o endpoint de contagens

​Payload de resposta do endpoint Counts

Artigos relacionados

​Guias

​Criando consultas de pesquisa

​Operadores do Enterprise

​Visão geral do produto

​Cronogramas de metadata

​2006

​2007

​2009

​2010

​2011

​2014

​2015

​2016

​2017

​2022

​2022

​Dicas de filtragem

​Perfis no X

​Posts originais e Retweets

​Classificações de idioma de Post

​Georreferenciamento de Posts

​Links e mídias compartilhados

​Perguntas frequentes (FAQ)

​Perguntas gerais sobre a API de Post de pesquisa

​Guia de solução de problemas de erros

​Referência da API

​APIs de busca Enterprise

​Métodos

​Autenticação

​Comportamento de solicitação/resposta

​Paginação

Paginação de dados

Paginação de contagens

Notas adicionais

​endpoint de data

POST /search/:product/:label

Padrão do endpoint:

Parâmetros da solicitação de dados

Detalhes adicionais

Exemplos de solicitações e respostas de dados

Exemplo de requisição POST

Visão geral

Tipos de solicitação

Solicitações de pesquisa (data)

Solicitações de contagem (Contagem de Posts)

Operadores disponíveis

Disponibilidade de dados / datas importantes

Atualizações de dados e mutabilidade

Solicitações single-thread vs. multi-thread

Lógica de novas tentativas

Introdução rápida

Introdução à enterprise Search Posts: 30-Day API

Acessando o endpoint de data

Payload de resposta do endpoint de dados

Acessando o endpoint de contagens

Payload de resposta do endpoint Counts

Introdução ao uso da Enterprise Search Posts: Full-Archive API

Acessando o endpoint de data

Acessando o endpoint de contagens

Payload de resposta do endpoint Counts

Guias

Criando consultas de pesquisa

Operadores do Enterprise

Visão geral do produto

Cronogramas de metadata

2006

2007

2009

2010

2011

2014

2015

2016

2017

2022

2022

Dicas de filtragem

Perfis no X

Posts originais e Retweets

Classificações de idioma de Post

Georreferenciamento de Posts

Links e mídias compartilhados

Perguntas frequentes (FAQ)

Perguntas gerais sobre a API de Post de pesquisa

Guia de solução de problemas de erros

Referência da API

APIs de busca Enterprise

Métodos

Autenticação

Comportamento de solicitação/resposta

Paginação

endpoint de data

endpoint de contagem

Exemplos de respostas de contagem

Códigos de resposta HTTP