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

# Construir una consulta

> Los endpoints de search aceptan una única consulta con una solicitud GET y devuelven un conjunto de Posts históricos. Referencia del nivel estándar de X API v2 sobre integración.

Los endpoints de search aceptan una única consulta con una solicitud GET y devuelven un conjunto de Posts históricos que coinciden con la consulta. Las consultas se componen de operadores que coinciden con una variedad de atributos de Post.

***

## Limitaciones de la consulta

Tus consultas estarán limitadas según el [nivel de acceso](/x-api/getting-started/about-x-api) que estés usando:

| Access level | Recent search    | Full-archive search |
| :----------- | :--------------- | :------------------ |
| Self-serve   | 512 caracteres   | 1,024 caracteres    |
| Enterprise   | 4,096 caracteres | 4,096 caracteres    |

***

## Disponibilidad de operadores

Aunque la mayoría de los operadores están disponibles para cualquier desarrollador, algunos están reservados para determinados niveles de acceso:

* **Operadores Core:** disponibles al usar cualquier [Project](/resources/fundamentals/developer-apps)
* **Operadores Advanced:** disponibles al usar un Project con determinados niveles de acceso

Consulta la [lista completa de operadores](/x-api/posts/search/integrate/operators) para conocer los detalles de disponibilidad.

***

## Tipos de operadores: independientes y que requieren conjunción

Los **operadores independientes** pueden usarse solos o junto con cualquier otro operador (incluidos aquellos que requieren conjunción).

Por ejemplo, esta consulta funciona porque `#hashtag` es un operador independiente:

```
#xapiv2
```

Los **operadores que requieren conjunción** no pueden usarse solos en una consulta; solo pueden usarse cuando se incluye al menos un operador independiente. Esto se debe a que usar estos operadores por sí solos coincidiría con un volumen extremadamente alto de Posts.

Por ejemplo, las siguientes consultas **no son compatibles** ya que contienen solo operadores que requieren conjunción:

```
has:media
```

```
has:links OR is:retweet
```

Si añadimos un operador independiente, como la frase `"X data"`, la consulta funciona correctamente:

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

***

## Operadores booleanos y agrupación

Combina múltiples operadores usando estas herramientas:

| Operator                    | Description                                                 | Example                                                                       |
| :-------------------------- | :---------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **AND** (espacio)           | Los Posts deben coincidir con ambas condiciones             | `snow day #NoSchool` coincide con Posts con "snow" AND "day" AND #NoSchool    |
| **OR**                      | Los Posts deben coincidir con cualquiera de las condiciones | `grumpy OR cat OR #meme` coincide con Posts con "grumpy" OR "cat" OR #meme    |
| **NOT** (guion)             | Excluye Posts que coincidan con esta condición              | `cat #meme -grumpy` coincide con Posts con "cat" y #meme pero NO con "grumpy" |
| **Agrupación** (paréntesis) | Agrupa operadores                                           | `(grumpy cat) OR (#meme has:images)` coincide con cualquiera de los grupos    |

<Note>
  **Una nota sobre las negaciones**

  * El operador `-is:nullcast` siempre debe estar negado
  * Los operadores negados no pueden usarse solos
  * No niegues operadores agrupados. En lugar de `skiing -(snow OR day OR noschool)`, usa `skiing -snow -day -noschool`
</Note>

***

## Orden de las operaciones

Al combinar AND y OR:

1. Los operadores conectados por lógica AND se combinan primero
2. Luego, se aplican los operadores conectados con lógica OR

**Ejemplos:**

| Query                    | Evaluated as               |
| :----------------------- | :------------------------- |
| `apple OR iphone ipad`   | `apple OR (iphone ipad)`   |
| `ipad iphone OR android` | `(iphone ipad) OR android` |

Para eliminar la incertidumbre, usa paréntesis:

```
(apple OR iphone) ipad
```

```
iphone (ipad OR android)
```

***

## Puntuación, diacríticos y sensibilidad a mayúsculas

**Diacríticos:** las consultas de búsqueda con acentos o diacríticos coinciden con Posts con o sin los acentos. Por ejemplo, `Diacrítica` coincide tanto con *Diacrítica* como con *Diacritica*.

**Sensibilidad a mayúsculas:** todos los operadores no distinguen entre mayúsculas y minúsculas. La consulta `cat` coincide con *cat*, *CAT* y *Cat*.

<Note>
  **Filtered stream se comporta de forma diferente**

  Al [construir reglas de filtered stream](/x-api/posts/filtered-stream/integrate/build-a-rule), las palabras clave con acentos solo coinciden con Posts que también incluyan el acento. Por ejemplo, `Diacrítica` solo coincide con *Diacrítica*, no con *Diacritica*.
</Note>

***

## Coincidencia de Quote Tweet

Al usar Search Posts, los operadores coinciden con el contenido del Quote Tweet pero **no** con el contenido del Post original que se citó.

<Note>
  [Filtered stream](/x-api/posts/filtered-stream/introduction) se comporta de manera diferente: coincide tanto con el Quote Tweet como con el contenido del Post original.
</Note>

***

## Especificidad y eficiencia

<Warning>
  No se recomienda usar operadores amplios como una sola palabra clave o un hashtag: coincidirán con un volumen masivo de Posts y consumirán rápidamente tus límites de uso.
</Warning>

**Consejos para crear consultas efectivas:**

1. **Empieza específico, luego amplía** — crea consultas dirigidas que devuelvan resultados relevantes
2. **Usa múltiples operadores** — combina operadores para reducir resultados
3. **Vigila tu recuento de caracteres** — toda la cadena de la consulta cuenta para el límite

**Ejemplo de progresión:**

```
# Demasiado amplio - más de 200,000 Posts por día
happy

# Mejor - añade filtro de idioma y exclusiones
(happy OR happiness) lang:en -birthday -is:retweet

# Aún mejor - 59 caracteres, más específico
(happy OR happiness) place_country:GB -birthday -is:retweet
```

***

## Construir una consulta de forma iterativa

### Paso 1: comienza con una consulta básica

```
happy OR happiness
```

### Paso 2: prueba y reduce según los resultados

Notamos Posts en muchos idiomas. Añade un filtro de idioma:

```
(happy OR happiness) lang:en
```

Estamos obteniendo felicitaciones de cumpleaños. Exclúyelas junto con los Retweets:

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

### Paso 3: amplía para una mejor cobertura

Queremos capturar más sentimiento. Añade palabras clave relacionadas:

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

### Paso 4: ajusta según las tendencias

Están apareciendo Posts de vacaciones. Exclúyelos:

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

***

## Añadir una consulta a tu solicitud

Usa el parámetro `query` y codifica en HTTP tu consulta:

```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"
```

***

## Ejemplos de consultas

### Seguimiento de un desastre natural

Coincide con Posts de agencias meteorológicas sobre el huracán Harvey:

**Consulta:**

```
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 de la solicitud:**

```
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álisis de sentimiento para #nowplaying

**Sentimiento 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
```

**Sentimiento 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
```

### Uso de Post annotations

Encuentra Posts en japonés sobre mascotas (no gatos) con imágenes usando el operador `context:`:

Primero, utiliza [Post lookup](/x-api/posts/lookup/introduction) con `tweet.fields=context_annotations` para identificar los IDs de domain.entity:

* Cats: `domain` 66, `entity` 852262932607926273
* Pets: `domain` 65, `entity` 852262932607926273

**Consulta:**

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

***

## Herramientas

<Card title="Herramienta Query Builder" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  Construye y prueba tus consultas de forma interactiva
</Card>

***

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Referencia 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 de operadores disponibles
  </Card>

  <Card title="Quickstart de búsqueda" 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">
    Realiza tu primera solicitud de búsqueda
  </Card>

  <Card title="Guía de integración" 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">
    Documentación completa de integración
  </Card>
</CardGroup>