Construir una consulta

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 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
Operadores Advanced: disponibles al usar un Project con determinados niveles de acceso

Consulta la lista completa de operadores 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

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

Orden de las operaciones

Al combinar AND y OR:

Los operadores conectados por lógica AND se combinan primero
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.

Filtered stream se comporta de forma diferenteAl construir reglas de filtered stream, 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.

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

Filtered stream se comporta de manera diferente: coincide tanto con el Quote Tweet como con el contenido del Post original.

Especificidad y eficiencia

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.

Consejos para crear consultas efectivas:

Empieza específico, luego amplía — crea consultas dirigidas que devuelvan resultados relevantes
Usa múltiples operadores — combina operadores para reducir resultados
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:

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

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Construir una consulta

Limitaciones de la consulta

Disponibilidad de operadores

Tipos de operadores: independientes y que requieren conjunción

Operadores booleanos y agrupación

Orden de las operaciones

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

Coincidencia de Quote Tweet

Especificidad y eficiencia

Construir una consulta de forma iterativa

Paso 1: comienza con una consulta básica

Paso 2: prueba y reduce según los resultados

Paso 3: amplía para una mejor cobertura

Paso 4: ajusta según las tendencias

Añadir una consulta a tu solicitud

Ejemplos de consultas

Seguimiento de un desastre natural

Análisis de sentimiento para #nowplaying

Uso de Post annotations

Herramientas

Herramienta Query Builder

Próximos pasos

Referencia de operadores

Quickstart de búsqueda

Guía de integración

​Limitaciones de la consulta

​Disponibilidad de operadores

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

​Operadores booleanos y agrupación

​Orden de las operaciones

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

​Coincidencia de Quote Tweet

​Especificidad y eficiencia

​Construir una consulta de forma iterativa

​Paso 1: comienza con una consulta básica

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

​Paso 3: amplía para una mejor cobertura

​Paso 4: ajusta según las tendencias

​Añadir una consulta a tu solicitud

​Ejemplos de consultas

​Seguimiento de un desastre natural

​Análisis de sentimiento para #nowplaying

​Uso de Post annotations

​Herramientas

Herramienta Query Builder

​Próximos pasos

Referencia de operadores

Quickstart de búsqueda

Guía de integración

Limitaciones de la consulta

Disponibilidad de operadores

Tipos de operadores: independientes y que requieren conjunción

Operadores booleanos y agrupación

Orden de las operaciones

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

Coincidencia de Quote Tweet

Especificidad y eficiencia

Construir una consulta de forma iterativa

Paso 1: comienza con una consulta básica

Paso 2: prueba y reduce según los resultados

Paso 3: amplía para una mejor cobertura

Paso 4: ajusta según las tendencias

Añadir una consulta a tu solicitud

Ejemplos de consultas

Seguimiento de un desastre natural

Análisis de sentimiento para #nowplaying

Uso de Post annotations

Herramientas

Próximos pasos