Skip to main content

​
Criando uma query

Limitações da query! Suas queries serão limitadas dependendo do nível de acesso que você estiver usando. Sua query pode ter até 512 caracteres para clientes pay-per-use, ou até 4.096 caracteres para clientes Enterprise. Se você tem acesso Enterprise, entre em contato com seu gerente de conta. Disponibilidade dos operadores Embora a maioria dos operadores esteja disponível para qualquer desenvolvedor, há vários que são reservados para aqueles que foram aprovados para acesso Enterprise. Listamos o nível de acesso ao qual cada operador está disponível na tabela lista de operadores usando os seguintes rótulos:
  • Operadores principais (core): disponíveis ao usar qualquer Project.
  • Operadores avançados: disponíveis ao usar um Project com acesso Enterprise

​
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, a query a seguir funcionará porque usa o operador #hashtag, que é independente: #xapiv2 Operadores que exigem conjunção não podem ser usados sozinhos em uma query; eles só podem ser usados quando pelo menos um operador independente estiver incluído na query. Isso ocorre porque usar esses operadores sozinhos seria excessivamente genérico e corresponderia a um volume extremamente alto de Posts. Por exemplo, as queries a seguir 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 passará a funcionar corretamente. “X data” has:mentions (has:media OR has:links)

​
Operadores booleanos e agrupamento

Se você quiser combinar múltiplos operadores em uma única query, tem as seguintes ferramentas à disposição: Uma nota sobre negações O operador -is:nullcast deve sempre ser negado. Operadores negados não podem ser usados sozinhos. Não negue um conjunto de operadores agrupados entre parênteses. Em vez disso, negue cada operador individualmente. Por exemplo, em vez de usar skiing -(snow OR day OR noschool), sugerimos que você use skiing -snow -day -noschool. Ordem das operações Ao combinar funcionalidades AND e OR, a seguinte ordem de operações ditará como sua query será avaliada.
  1. Operadores conectados por lógica AND são combinados primeiro
  2. Em seguida, operadores conectados com lógica OR são aplicados
Por exemplo:
  • apple OR iphone ipad seria avaliado como apple OR (iphone ipad)
  • ipad iphone OR android seria avaliado como (iphone ipad) OR android
Para eliminar a incerteza e garantir que sua query seja avaliada como pretendido, agrupe os termos com parênteses onde for apropriado. Por exemplo:
  • (apple OR iphone) ipad
  • iphone (ipad OR android)
Pontuação, diacríticos e sensibilidade a maiúsculas/minúsculas Se você especificar uma query com palavra-chave ou hashtag com acentos ou diacríticos, ela corresponderá ao texto do Post que contenha tanto o termo com os acentos e diacríticos quanto os termos com caracteres normais. Por exemplo, queries com a palavra-chave Diacrítica ou hashtag #cumpleaños corresponderão a Diacrítica ou #cumpleaños, bem como a Diacritica ou #cumpleanos sem o til í ou o eñe. Caracteres com acentos ou diacríticos são tratados da mesma forma que caracteres normais e não são tratados como limites de palavra. Por exemplo, uma query com a palavra-chave cumpleaños somente corresponderá a atividades contendo a palavra cumpleaños e não corresponderá a atividades contendo cumplea, cumplean ou os. Todos os operadores são avaliados de forma insensível a maiúsculas/minúsculas. Por exemplo, a query cat corresponderá a Posts com todos os seguintes: cat, CAT, Cat. O comportamento de correspondência do filtered stream age de forma diferente do Post counts. Ao criar uma regra de filtered stream, saiba que palavras-chave e hashtags que incluem acentos e diacríticos corresponderão apenas a termos que também incluam o acento e o diacrítico, e não corresponderão a termos que usem caracteres normais. Por exemplo, regras de filtered stream que incluem uma palavra-chave Diacrítica ou hashtag #cumpleaños corresponderão apenas aos termos Diacrítica e #cumpleaños, e não corresponderão a Diacritica ou #cumpleanos sem o til í ou o eñe. Especificidade e eficiência Ao começar a montar sua query, é importante ter em mente algumas coisas.
  • Usar operadores independentes amplos para sua query, como uma única palavra-chave ou #hashtag, geralmente não é recomendado, pois provavelmente corresponderá a um volume enorme de Posts. Criar uma query mais robusta resultará em um conjunto mais específico de Posts correspondentes e, esperançosamente, aumentará a precisão dos seus Post counts para ajudar você a obter insights mais valiosos.
    • Por exemplo, se sua query fosse apenas a palavra-chave happy, você provavelmente obteria algo entre 200.000 e 300.000 Posts por dia.
    • Adicionar mais operadores condicionais restringe seus resultados, por exemplo (happy OR happiness) place_country:GB -birthday -is:retweet
  • Escrever queries eficientes também ajuda a se manter dentro da restrição de tamanho de caracteres da query. A contagem de caracteres inclui toda a string da query, incluindo espaços e operadores.
    • Por exemplo, a query a seguir tem 59 caracteres: (happy OR happiness) place_country:GB -birthday -is:retweet
Comportamento de correspondência de Quote Tweets Ao usar os endpoints de Post counts, os operadores não corresponderão ao conteúdo do Post original que foi citado, mas corresponderão ao conteúdo incluído no Quote Tweet. No entanto, observe que o filtered stream corresponderá tanto ao conteúdo do Post original que foi citado quanto ao conteúdo do Quote Tweet. Construindo uma query iterativamente Teste sua query cedo e com frequência Conseguir que uma query retorne os resultados “certos” na primeira tentativa é raro. Há tanto no X que pode ou não ser óbvio à primeira vista, e a sintaxe de query descrita acima pode ser difícil de alinhar com a query desejada. Conforme você monta uma query, é importante testá-la periodicamente usando um dos endpoints de Search Post para garantir que os Posts que correspondem à sua query sejam relevantes para o seu caso de uso. Para esta seção, vamos começar com a seguinte query e ajustá-la com base nos resultados que recebermos durante nosso teste: happy OR happiness Use os resultados para refinar a query Ao testar a query com Search Posts, você deve examinar os Posts retornados para ver se eles incluem os dados que você espera e deseja receber. Começar com uma query ampla e um superconjunto de Posts correspondentes permite que você revise o resultado e refine a query para filtrar resultados indesejados. Ao testar a query de exemplo, notamos que estávamos recebendo Posts em diversos idiomas. Neste caso, queremos receber apenas Posts em inglês, então vamos adicionar o operador lang:: (happy OR happiness) lang:en O teste retornou vários Posts desejando feliz aniversário às pessoas, então vamos adicionar -birthday como operador de palavra-chave negado. Também queremos receber apenas Posts originais, portanto adicionamos o operador negado -is:retweet: (happy OR happiness) lang:en -birthday -is:retweet Ajuste para inclusão quando necessário Se você notar que não está recebendo via Search Posts os dados que espera e sabe que existem Posts que deveriam retornar, pode ser necessário ampliar sua query removendo operadores que possam estar filtrando os dados desejados. Para o nosso exemplo, notamos que havia outros Posts em nossa timeline pessoal que expressavam a emoção que estamos procurando e não foram incluídos nos resultados do teste. Para garantir uma cobertura maior, vamos adicionar as palavras-chave excited e elated. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet Ajuste para tendências/picos populares no período As tendências surgem e desaparecem rapidamente no X. Manter sua query deve ser um processo ativo. Se você planeja usar uma query por um tempo, sugerimos que verifique periodicamente os dados que está recebendo para ver se precisa fazer algum ajuste. No nosso exemplo, notamos que começamos a receber alguns Posts desejando “happy holidays”. Como não queremos que esses Posts sejam incluídos em nossos resultados, vamos adicionar uma palavra-chave negada -holidays. (happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays Depois de testar e iterar adequadamente sobre sua query, você pode começar a enviá-la com os endpoints de Post counts para começar a receber apenas o volume de Posts em vez dos payloads completos dos Posts.

​
Adicionando uma query à sua requisição

Para adicionar sua query à requisição, você deve usar o parâmetro query. Como em qualquer parâmetro de query, você deve garantir que a query desenvolvida esteja codificada em HTTP. Aqui está um exemplo de como isso pode ficar usando um comando cURL. Se quiser usar este comando, certifique-se de substituir $BEARER_TOKEN pelo seu próprio Bearer Token:

​
Exemplos de query

Acompanhando um desastre natural A query a seguir correspondeu a Posts originais de agências e estações meteorológicas que discutem o Furacão Harvey, que atingiu Houston em 2017. Veja como a query ficaria sem a codificação HTTP: 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 E aqui está como a query ficaria com a codificação HTTP, o parâmetro query e a URI de Post counts recentes: https://api.x.com/2/tweets/counts/recent?query=-is%3Aretweet%20has%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) Analisando o sentimento de uma conversa A próxima regra pode ser usada para entender melhor o sentimento da conversa que se desenvolve em torno da hashtag #nowplaying, mas limitada apenas a Posts publicados dentro de