Guía de integración

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

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"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Buscar publicaciones recientes
for page in client.posts.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"],
    max_results=100
):
    for post in page.data:
        print(f"{post.text} - Likes: {post.public_metrics.like_count}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Buscar publicaciones recientes
const paginator = client.posts.searchRecent("python", {
  tweetFields: ["created_at", "public_metrics", "author_id"],
  expansions: ["author_id", "attachments.media_keys"],
  userFields: ["username", "verified"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((post) => {
    console.log(`${post.text} - Likes: ${post.public_metrics?.like_count}`);
  });
}

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

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

Ejemplo

cURL

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

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# El SDK se encarga de la paginación automáticamente
all_posts = []

for page in client.posts.search_recent(query="python", max_results=100):
    if page.data:
        all_posts.extend(page.data)

print(f"Se encontraron {len(all_posts)} publicaciones")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

async function getAllResults(query) {
  const allPosts = [];

  // El SDK se encarga de la paginación automáticamente
  const paginator = client.posts.searchRecent(query, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allPosts.push(...page.data);
    }
  }

  return allPosts;
}

// Uso
const posts = await getAllResults("python");
console.log(`Se encontraron ${posts.length} publicaciones`);

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

​Autenticación

​Búsqueda reciente

​Búsqueda en el archivo completo

​Creación de consultas

​Límites de longitud de las consultas

​Tipos de operadores

Crear una consulta

Referencia de operadores

​Campos y expansiones

​Ejemplo de solicitud

​Expansions disponibles

Guía de campos y expansions

​Paginación

​Cómo funciona

​Ejemplo

Guía de paginación

​Edición de Publicaciones

​Consideraciones

Conceptos básicos sobre la edición de Publicaciones

​Mejores prácticas

Empieza de forma específica

Prueba iterativamente

Gestiona la paginación

Almacena en caché los resultados

​Próximos pasos

Crear una consulta

Referencia de operadores

Paginación

Referencia de la API

Autenticación

Búsqueda reciente

Búsqueda en el archivo completo

Creación de consultas

Límites de longitud de las consultas

Tipos de operadores

Campos y expansiones

Ejemplo de solicitud

Expansions disponibles

Paginación

Cómo funciona

Ejemplo

Edición de Publicaciones

Consideraciones

Mejores prácticas

Próximos pasos