> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar uma query

> Os endpoints de busca aceitam uma única query com uma requisição GET e retornam um conjunto de Posts históricos. Referência para o tier standard da X API v2 sobre integrate.

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](/x-api/getting-started/about-x-api) 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](/resources/fundamentals/developer-apps)
* **Operadores Advanced:** Disponíveis ao usar um Project com certos níveis de acesso

Veja a [lista completa de operadores](/x-api/posts/search/integrate/operators) 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           |

<Note>
  **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`
</Note>

***

## Ordem das operações

Ao combinar AND e OR:

1. Operadores conectados por lógica AND são combinados primeiro
2. 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*.

<Note>
  **O filtered stream se comporta de forma diferente**

  Ao [criar regras de filtered stream](/x-api/posts/filtered-stream/integrate/build-a-rule), 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*.
</Note>

***

## 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.

<Note>
  O [filtered stream](/x-api/posts/filtered-stream/introduction) se comporta de forma diferente — corresponde tanto ao conteúdo do Quote Tweet quanto ao do Post original.
</Note>

***

## Especificidade e eficiência

<Warning>
  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.
</Warning>

**Dicas para criar queries eficazes:**

1. **Comece específico e depois amplie** — Crie queries direcionadas que retornem resultados relevantes
2. **Use múltiplos operadores** — Combine operadores para restringir resultados
3. **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:

```bash theme={null}
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](/x-api/posts/lookup/introduction) 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
```

***

## Ferramentas

<Card title="Query Builder Tool" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  Crie e teste suas queries interativamente
</Card>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Referência de operadores" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/posts/search/integrate/operators" width="24" height="24" data-path="icons/xds/icon-bulleted-list.svg">
    Lista completa dos operadores disponíveis
  </Card>

  <Card title="Quickstart de busca" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/recent-search" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    Faça sua primeira requisição de busca
  </Card>

  <Card title="Guia de integração" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/search/integrate/overview" width="24" height="24" data-path="icons/xds/icon-book.svg">
    Documentação completa de integração
  </Card>
</CardGroup>