Guía de integración

Conceptos clave y buenas prácticas para integrar la búsqueda de Publicaciones

Esta guía cubre los conceptos clave que necesitas conocer para integrar los endpoints de búsqueda de Publicaciones en tu aplicación.

---

​

Autenticación

​

Búsqueda reciente

La búsqueda reciente es compatible con varios métodos de autenticación:

Método	Caso de uso
OAuth 2.0 App-Only	Datos públicos de publicaciones
OAuth 2.0 Authorization Code with PKCE	Métricas privadas
OAuth 1.0a User Context	Métricas privadas

​

Búsqueda en el archivo completo

La búsqueda en el archivo completo solo admite la autenticación OAuth 2.0 App-Only.

Las métricas privadas (non_public_metrics, organic_metrics, promoted_metrics) no están disponibles con la búsqueda en el archivo completo porque solo admite autenticación App-Only.

---

​

Creación de consultas

Las consultas usan operadores para buscar Publicaciones que coincidan. Combina operadores utilizando lógica booleana:

(AI OR "machine learning") lang:en -is:retweet has:links

​

Límites de longitud de las consultas

Nivel de acceso	Búsqueda reciente	Búsqueda en el archivo completo
Autoservicio	512 caracteres	1,024 caracteres
Enterprise	4,096 caracteres	4,096 caracteres

​

Tipos de operadores

Tipo	Descripción	Ejemplo
Independiente	Se puede usar por sí solo	#python, from:user
Requiere conjunción	Debe usarse con un operador independiente	has:media, is:retweet

Crear una consulta

Obtén información detallada sobre la sintaxis de las consultas

Referencia de operadores

Ver todos los operadores disponibles

---

​

Campos y expansiones

De forma predeterminada, la respuesta solo incluye id, text y edit_history_tweet_ids. Usa los parámetros para solicitar datos adicionales.

​

Ejemplo de solicitud

cURL

shellscript

curl "https://api.x.com/2/tweets/search/recent?\
query=python&\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​

Expansions disponibles

Expansion	Devuelve
author_id	Objeto de usuario del autor
attachments.media_keys	Objetos multimedia adjuntos
attachments.poll_ids	Objetos de encuestas adjuntas
referenced_tweets.id	Publicaciones citadas o respondidas
geo.place_id	Objetos de lugar
entities.mentions.username	Objetos de usuario mencionados

Guía de campos y expansions

Obtén más información sobre cómo personalizar las respuestas

---

​

Paginación

Los endpoints de búsqueda devuelven resultados en páginas. Usa el next_token de la respuesta para recuperar páginas adicionales.

​

Cómo funciona

1. Realiza tu solicitud inicial con max_results
2. Consulta el objeto meta para ver si incluye un next_token
3. Incluye next_token en las solicitudes posteriores
4. Repite hasta que ya no se devuelva ningún next_token

​

Ejemplo

cURL

shellscript

# Primera solicitud
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# Solicitud siguiente con token de paginación
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100&next_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Guía de paginación

Obtén más información sobre la paginación

---

​

Edición de Publicaciones

Las Publicaciones se pueden editar hasta 5 veces en un plazo de 30 minutos. Los endpoints de búsqueda siempre devuelven la versión más reciente.

​

Consideraciones

• edit_history_tweet_ids contiene todos los id de Publicación (de la más antigua a la más reciente)
• Las Publicaciones obtenidas después de la ventana de 30 minutos representan la versión final
• En casos de uso casi en tiempo real, las Publicaciones recién publicadas aún pueden editarse

Conceptos básicos sobre la edición de Publicaciones

Obtén más información sobre cómo editar Publicaciones

---

​

Mejores prácticas

Empieza de forma específica

Usa varios operadores para acotar los resultados y reducir el ruido.

Prueba iterativamente

Empieza con un criterio amplio y luego afínalo según los resultados.

Gestiona la paginación

Implementa una paginación adecuada para grandes conjuntos de resultados.

Almacena en caché los resultados

Almacena los resultados localmente para evitar solicitudes repetidas.

---

​

Próximos pasos

Crear una consulta

Domina la sintaxis de las consultas

Referencia de operadores

Todos los operadores disponibles

Paginación

Gestiona grandes conjuntos de resultados

Referencia de la API

Documentación completa del endpoint