Saltar al contenido principal
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 accesoBúsqueda recienteBúsqueda en archivo completo
Self-serve512 caracteres1,024 caracteres
Enterprise4,096 caracteres4,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:
OperadorDescripciónEjemplo
AND (space)Las Publicaciones deben coincidir con ambas condicionessnow day #NoSchool coincide con Publicaciones que contienen “snow”, “day” y #NoSchool
ORLas Publicaciones deben coincidir con al menos una de las condicionesgrumpy OR cat OR #meme coincide con Publicaciones que contienen “grumpy”, “cat” o #meme
NOT (dash)Excluye las Publicaciones que coinciden con esta condicióncat #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:
QueryEvaluated as
apple OR iphone ipadapple 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 diferenteAl 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
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