Crear una consulta

Aprende a crear consultas de búsqueda usando operadores

Los endpoints de búsqueda aceptan una única consulta en una solicitud GET y devuelven un conjunto de Publicaciones históricas que coinciden con la consulta. Las consultas están formadas por operadores que se aplican a una variedad de atributos de las Publicaciones.

---

Limitaciones de las consultas

Tus consultas estarán limitadas en función del nivel de acceso que estés utilizando:

Nivel de acceso	Búsqueda reciente	Búsqueda en archivo completo
Self-serve	512 caracteres	1,024 caracteres
Enterprise	4,096 caracteres	4,096 caracteres

---

Disponibilidad de operadores

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

• Operadores básicos: Disponibles al utilizar cualquier Project
• Operadores avanzados: Disponibles al utilizar un Project con ciertos niveles de acceso

Consulta la lista completa de operadores para obtener más información sobre su disponibilidad.

---

Tipos de operadores: independientes y que requieren conjunción

Los operadores independientes se pueden usar 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 por sí solos en una consulta; solo pueden utilizarse cuando se incluye al menos un operador independiente. Esto se debe a que usar estos operadores por sí solos generaría un volumen extremadamente alto de Publicaciones.

Por ejemplo, las siguientes consultas no se admiten ya que contienen únicamente operadores que requieren conjunción:

has:media

has:links OR is:retweet

Si agregamos un operador independiente, como la expresión "X data", la consulta funciona correctamente:

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

---

Operadores booleanos y agrupación

Encadena múltiples operadores usando estas herramientas:

Operador	Descripción	Ejemplo
AND (space)	Las Publicaciones deben coincidir con ambas condiciones	snow day #NoSchool coincide con Publicaciones que contienen “snow”, “day” y #NoSchool
OR	Las Publicaciones deben coincidir con al menos una de las condiciones	grumpy OR cat OR #meme coincide con Publicaciones que contienen “grumpy”, “cat” o #meme
NOT (dash)	Excluye las Publicaciones que coinciden con esta condición	cat #meme -grumpy coincide con Publicaciones que contienen “cat” y #meme pero NO “grumpy”
Grouping (parentheses)	Agrupa operadores	(grumpy cat) OR (#meme has:images) coincide con cualquiera de los grupos

Una nota sobre negaciones

• El operador -is:nullcast siempre debe usarse negado
• No se pueden usar operadores negados de forma aislada
• No niegues operadores agrupados. En lugar de skiing -(snow OR day OR noschool), usa skiing -snow -day -noschool

---

Orden de operaciones

Al combinar AND y OR:

1. Primero se combinan los operadores conectados mediante la lógica AND
2. Luego se aplican los operadores conectados mediante la 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, signos diacríticos y distinción entre mayúsculas y minúsculas

Signos diacríticos: Las consultas de búsqueda con acentos o signos diacríticos encuentran Publicaciones tanto con como sin acentos. Por ejemplo, Diacrítica coincide con Diacrítica y Diacritica.

Distinción entre mayúsculas y minúsculas: Todos los operadores son insensibles a mayúsculas y minúsculas. La consulta cat coincide con cat, CAT y Cat.

El stream filtrado se comporta de manera diferente

Al crear reglas de stream filtrado, las palabras clave con acentos solo coinciden con Publicaciones que también incluyan el acento. Por ejemplo, Diacrítica solo coincide con Diacrítica, no con Diacritica.

---

Coincidencia de Quote Tweet

Al usar Search Posts, los operadores se aplican al contenido del Quote Tweet, pero no al contenido de la Publicación original citada.

Filtered stream se comporta de forma diferente: realiza coincidencias tanto en el Quote Tweet como en el contenido de la Publicación original.

---

Especificidad y eficiencia

No se recomienda usar operadores amplios como una sola palabra clave o hashtag, ya que harán coincidir un volumen masivo de Publicaciones y consumirán rápidamente tus límites de uso.

Consejos para crear consultas eficaces:

1. Empieza con algo específico y luego amplía — Crea consultas dirigidas que devuelvan resultados relevantes
2. Usa múltiples operadores — Combina operadores para acotar los resultados
3. Controla el número de caracteres — Toda la cadena de consulta cuenta para el límite

Ejemplo de progresión:

# Too broad - 200,000+ Posts per day
happy

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

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet

---

Crear una consulta paso a paso

Paso 1: Empieza con una consulta básica

happy OR happiness

Paso 2: Haz pruebas y acota según los resultados

Detectamos Publicaciones en muchos idiomas. Añade un filtro de idioma:

(happy OR happiness) lang:en

Estamos recibiendo mensajes de felicitación de cumpleaños. Exclúyelos y los Retweets:

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

Paso 3: Ampliar para mejorar la cobertura

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

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

Paso 4: Ajustar según las tendencias

Empiezan a aparecer Publicaciones sobre festividades. Exclúyelas:

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

---

Agregar una consulta a tu solicitud

Utiliza el parámetro query y codifica la consulta para 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"

---

Ejemplos de consultas

Seguimiento de un desastre natural

Que coincida con Publicaciones 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 anotaciones de Publicaciones

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

Primero, usa Post lookup con tweet.fields=context_annotations para identificar los id 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

Herramienta para generar consultas

Crea y prueba tus consultas de forma interactiva

---

Próximos pasos

Referencia de operadores

Lista completa de operadores disponibles

Inicio rápido de búsqueda

Realiza tu primera solicitud de búsqueda

Guía de integración

Documentación completa sobre la integración