Criar uma query

Os endpoints de busca aceitam uma única query com uma requisição GET e retornam um conjunto de Posts históricos que correspondem à query. As queries são compostas por operadores que correspondem a diversos atributos de Post.

Limitações da query

Suas queries serão limitadas dependendo do nível de acesso que você estiver usando:

Nível de acesso	Recent search	Full-archive search
Self-serve	512 caracteres	1.024 caracteres
Enterprise	4.096 caracteres	4.096 caracteres

Disponibilidade dos operadores

Embora a maioria dos operadores esteja disponível para qualquer desenvolvedor, alguns são reservados para certos níveis de acesso:

Operadores Core: Disponíveis ao usar qualquer Project
Operadores Advanced: Disponíveis ao usar um Project com certos níveis de acesso

Veja a lista completa de operadores para detalhes de disponibilidade.

Tipos de operador: independentes e que exigem conjunção

Operadores independentes podem ser usados sozinhos ou junto com quaisquer outros operadores (incluindo os que exigem conjunção). Por exemplo, esta query funciona porque #hashtag é um operador independente:

#xapiv2

Operadores que exigem conjunção não podem ser usados sozinhos em uma query; só podem ser usados quando pelo menos um operador independente estiver incluído. Isso ocorre porque usar esses operadores sozinhos corresponderia a um volume extremamente alto de Posts. Por exemplo, as seguintes queries não são suportadas, pois contêm apenas operadores que exigem conjunção:

has:media

has:links OR is:retweet

Se adicionarmos um operador independente, como a frase "X data", a query funciona corretamente:

"X data" has:mentions (has:media OR has:links)

Operadores booleanos e agrupamento

Combine múltiplos operadores usando estas ferramentas:

Operador	Descrição	Exemplo
AND (espaço)	Posts devem corresponder a ambas as condições	`snow day #NoSchool` corresponde a Posts com “snow” AND “day” AND #NoSchool
OR	Posts devem corresponder a qualquer condição	`grumpy OR cat OR #meme` corresponde a Posts com “grumpy” OR “cat” OR #meme
NOT (traço)	Excluir Posts que correspondam a esta condição	`cat #meme -grumpy` corresponde a Posts com “cat” e #meme mas NOT “grumpy”
Agrupamento (parênteses)	Agrupar operadores	`(grumpy cat) OR (#meme has:images)` corresponde a qualquer grupo

Uma nota sobre negações

O operador -is:nullcast deve sempre ser negado
Operadores negados não podem ser usados sozinhos
Não negue operadores agrupados. Em vez de skiing -(snow OR day OR noschool), use skiing -snow -day -noschool

Ordem das operações

Ao combinar AND e OR:

Operadores conectados por lógica AND são combinados primeiro
Em seguida, operadores conectados com lógica OR são aplicados

Exemplos:

Query	Avaliada como
`apple OR iphone ipad`	`apple OR (iphone ipad)`
`ipad iphone OR android`	`(iphone ipad) OR android`

Para eliminar incertezas, use parênteses:

(apple OR iphone) ipad

iphone (ipad OR android)

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Diacríticos: Queries de busca com acentos ou diacríticos correspondem a Posts com e sem os acentos. Por exemplo, Diacrítica corresponde a Diacrítica e a Diacritica. Sensibilidade a maiúsculas/minúsculas: Todos os operadores são insensíveis a maiúsculas/minúsculas. A query cat corresponde a cat, CAT e Cat.

O filtered stream se comporta de forma diferenteAo criar regras de filtered stream, palavras-chave com acentos correspondem apenas a Posts que também incluam o acento. Por exemplo, Diacrítica corresponde apenas a Diacrítica, não a Diacritica.

Correspondência de Quote Tweet

Ao usar o Search Posts, os operadores correspondem ao conteúdo do Quote Tweet, mas não ao conteúdo do Post original que foi citado.

O filtered stream se comporta de forma diferente — corresponde tanto ao conteúdo do Quote Tweet quanto ao do Post original.

Especificidade e eficiência

Usar operadores amplos como uma única palavra-chave ou hashtag não é recomendado — isso corresponderá a um volume enorme de Posts e consumirá rapidamente seus limites de uso.

Dicas para criar queries eficazes:

Comece específico e depois amplie — Crie queries direcionadas que retornem resultados relevantes
Use múltiplos operadores — Combine operadores para restringir resultados
Fique atento à contagem de caracteres — Toda a string da query conta para o limite

Exemplo de progressão:

# Muito amplo - 200.000+ Posts por dia
happy

# Melhor - adiciona filtro de idioma e exclusões
(happy OR happiness) lang:en -birthday -is:retweet

# Ainda melhor - 59 caracteres, mais específico
(happy OR happiness) place_country:GB -birthday -is:retweet

Construindo uma query iterativamente

Passo 1: Comece com uma query básica

happy OR happiness

Passo 2: Teste e refine com base nos resultados

Notamos Posts em vários idiomas. Adicione um filtro de idioma:

(happy OR happiness) lang:en

Estamos recebendo felicitações de aniversário. Exclua-as e os Retweets:

(happy OR happiness) lang:en -birthday -is:retweet

Passo 3: Amplie para melhor cobertura

Queremos capturar mais sentimento. Adicione palavras-chave relacionadas:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

Passo 4: Ajuste para tendências

Posts de feriados estão aparecendo. Exclua-os:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

Adicionando uma query à sua requisição

Use o parâmetro query e codifique sua query em HTTP:

curl "https://api.x.com/2/tweets/search/recent?\
query=cat%20has%3Amedia%20-grumpy&\
tweet.fields=created_at&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Exemplos de query

Acompanhando um desastre natural

Corresponde a Posts de agências meteorológicas sobre o Furacão Harvey: Query:

has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet

URL completa da requisição:

https://api.x.com/2/tweets/search/recent?query=has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)%20-is%3Aretweet

Análise de sentimento para #nowplaying

Sentimento positivo:

#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing

Sentimento negativo:

#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible

Usando Post annotations

Encontre Posts em japonês sobre pets (não gatos) com imagens usando o operador context:: Primeiro, use o Post lookup com tweet.fields=context_annotations para identificar IDs de domain.entity:

Gatos: domain 66, entity 852262932607926273
Pets: domain 65, entity 852262932607926273

Query:

context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Criar uma query

Limitações da query

Disponibilidade dos operadores

Tipos de operador: independentes e que exigem conjunção

Operadores booleanos e agrupamento

Ordem das operações

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Correspondência de Quote Tweet

Especificidade e eficiência

Construindo uma query iterativamente

Passo 1: Comece com uma query básica

Passo 2: Teste e refine com base nos resultados

Passo 3: Amplie para melhor cobertura

Passo 4: Ajuste para tendências

Adicionando uma query à sua requisição

Exemplos de query

Acompanhando um desastre natural

Análise de sentimento para #nowplaying

Usando Post annotations

Ferramentas

Query Builder Tool

Próximos passos

Referência de operadores

Quickstart de busca

Guia de integração

​Limitações da query

​Disponibilidade dos operadores

​Tipos de operador: independentes e que exigem conjunção

​Operadores booleanos e agrupamento

​Ordem das operações

​Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

​Correspondência de Quote Tweet

​Especificidade e eficiência

​Construindo uma query iterativamente

​Passo 1: Comece com uma query básica

​Passo 2: Teste e refine com base nos resultados

​Passo 3: Amplie para melhor cobertura

​Passo 4: Ajuste para tendências

​Adicionando uma query à sua requisição

​Exemplos de query

​Acompanhando um desastre natural

​Análise de sentimento para #nowplaying

​Usando Post annotations

​Ferramentas

Query Builder Tool

​Próximos passos

Referência de operadores

Quickstart de busca

Guia de integração

Limitações da query

Disponibilidade dos operadores

Tipos de operador: independentes e que exigem conjunção

Operadores booleanos e agrupamento

Ordem das operações

Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas

Correspondência de Quote Tweet

Especificidade e eficiência

Construindo uma query iterativamente

Passo 1: Comece com uma query básica

Passo 2: Teste e refine com base nos resultados

Passo 3: Amplie para melhor cobertura

Passo 4: Ajuste para tendências

Adicionando uma query à sua requisição

Exemplos de query

Acompanhando um desastre natural

Análise de sentimento para #nowplaying

Usando Post annotations

Ferramentas

Próximos passos