Paginación

​

Paginación en la búsqueda reciente

​

Introducción

Las consultas de búsqueda normalmente devuelven más Publicaciones de las que se pueden incluir en una única respuesta de la API. Cuando eso sucede, los datos se devuelven en una serie de “páginas”. La paginación se refiere a los métodos para solicitar todas las páginas con el fin de recuperar el conjunto completo de datos.

A continuación, se muestran detalles fundamentales sobre la paginación en búsquedas recientes:

• Los endpoints de búsqueda reciente responderán a una consulta con al menos una página y proporcionarán un next_token en su respuesta JSON si hay páginas adicionales disponibles. Para recibir todas las Publicaciones coincidentes, este proceso puede repetirse hasta que no se incluya ningún token en la respuesta.

• El next_token no caduca. Varias solicitudes que utilicen el mismo valor de next_token recibirán los mismos resultados, independientemente de cuándo se realice la solicitud.

• Las Publicaciones se entregan en orden cronológico inverso, en la zona horaria UTC. Esto es así dentro de páginas individuales, así como entre varias páginas: 

  • La primera Publicación en la primera respuesta será la más reciente que coincida con tu consulta.
  • La última Publicación en la última respuesta será la más antigua que coincida con tu consulta.

• El parámetro de solicitud max_results te permite configurar el número de Publicaciones que se devuelven por respuesta. El valor predeterminado es 10 Publicaciones y el máximo es 100. 

• Toda implementación de paginación implicará extraer los next_token del cuerpo de la respuesta e incluirlos en la solicitud de búsqueda de la “siguiente página”. Consulta más abajo para obtener más detalles sobre cómo construir estas solicitudes de “siguiente página”.  

El endpoint de búsqueda reciente se diseñó para admitir dos patrones de uso fundamentales:

• Obtener datos históricos - Solicitar Publicaciones que coincidan dentro de un período de tiempo de interés. Normalmente son solicitudes puntuales que respaldan la investigación histórica. Las solicitudes de búsqueda pueden basarse en los parámetros de solicitud start_time y end_time. El endpoint de búsqueda reciente responde con Publicaciones entregadas en orden cronológico inverso, comenzando por la Publicación más reciente que coincida. 

• Sondeo (polling) - Solicitar Publicaciones que coincidan y que se hayan publicado desde la última Publicación recibida. Estos casos de uso suelen tener un enfoque casi en tiempo real y se caracterizan por solicitudes frecuentes que “escuchan” nuevas Publicaciones de interés. El endpoint de búsqueda reciente proporciona el parámetro de solicitud since_id para admitir el patrón de “polling”. Para ayudar con la navegación por los id de las Publicaciones, también está disponible el parámetro de solicitud until_id.  

A continuación, analizaremos el modo histórico. Este es el modo predeterminado del endpoint de búsqueda reciente y muestra los fundamentos de la paginación. Después analizaremos ejemplos de casos de uso de sondeo. Cuando el sondeo desencadena la paginación, hay un paso adicional para gestionar las solicitudes de búsqueda.  

​

Recuperar datos históricos

Esta sección describe cómo puedes recuperar Publicaciones de un período de interés (actualmente limitado a los últimos siete días) usando los parámetros de solicitud start_time y end_time. Las solicitudes históricas suelen ser solicitudes puntuales para respaldar tareas de investigación y análisis. 

Realizar solicitudes para un período de datos es el modo predeterminado del endpoint de búsqueda reciente. Si una solicitud de búsqueda no especifica un parámetro de solicitud start_time, end_time o since_id, el end_time tendrá como valor predeterminado “now” (en realidad, 30 segundos antes del momento de la consulta) y el start_time tendrá como valor predeterminado siete días antes.

El endpoint responderá con la primera “página” de Publicaciones en orden cronológico inverso, comenzando por la Publicación más reciente. La carga útil JSON de la respuesta también incluirá un next_token si hay páginas adicionales de datos. Para recopilar el conjunto completo de Publicaciones coincidentes, independientemente del número de páginas, debes realizar solicitudes hasta que no se proporcione ningún next_token. 

Por ejemplo, aquí tienes una solicitud inicial de Publicaciones con la palabra clave snow de la última semana:

https://api.x.com/2/tweets/search/recent?query=snow

La respuesta incluye las 10 Publicaciones más recientes, junto con estos atributos “meta” en la respuesta JSON:

"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }

Para recuperar las siguientes 10 Publicaciones, agrega este next_token a la solicitud original. La solicitud sería:

https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql

El proceso de buscar un next_token e incluirlo en una solicitud posterior se puede repetir hasta que se hayan recopilado todas (o cierta cantidad de) Publicaciones, o hasta que se haya realizado un número específico de solicitudes. Si la fidelidad de los datos (recopilar todas las coincidencias de tu consulta) es clave para tu caso de uso, bastará con un sencillo diseño de “repeat until request.next_token is null”.

​

Casos de uso de sondeo y escucha

Esta sección describe cómo puedes recuperar Publicaciones recientes sondeando el endpoint de búsqueda reciente con el parámetro de solicitud since_id. 

En los casos de uso de sondeo, las consultas de “¿hay nuevas Publicaciones de interés?” se realizan de forma continua y frecuente. A diferencia de los casos de uso históricos, que basan las solicitudes en el tiempo, los casos de uso de sondeo normalmente basan las solicitudes en IDs de Publicación.

Lo fundamental en el patrón de uso de sondeo es que cada nueva Publicación tiene un ID único que se “emite” desde la plataforma de X generalmente en orden ascendente. Si una Publicación tiene un ID menor que otra, significa que se publicó antes.

El endpoint de búsqueda reciente permite navegar por el archivo de Publicaciones mediante el ID de la Publicación. Las respuestas del endpoint incluyen los IDs de Publicación oldest_id y newest_id. En el modo de sondeo, las solicitudes se realizan con since_id establecido en el ID más grande/más reciente recibido hasta el momento. 

Por ejemplo, supongamos que se realiza una consulta sobre nuevas Publicaciones sobre la nieve cada cinco minutos, y que la última Publicación que recibimos tenía un ID de Publicación de 10000. Cuando llega el momento de sondear, la solicitud es la siguiente:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000

A continuación, supongamos que se publicaron siete Publicaciones desde nuestra última solicitud. Como todas caben en una sola “página” de datos, no hay next_token. La respuesta proporciona el ID de Publicación de la Publicación más reciente (la más nueva):

"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }

Para hacer la siguiente consulta de sondeo (polling), este valor de newest_id se utiliza para establecer el siguiente parámetro since_id:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000

Cuando hay más datos disponibles y se proporcionan tokens next, solo se necesita el valor newest_id de la primera página de resultados. Cada página de datos incluirá valores newest_id y oldest_id, pero el valor proporcionado en la primera página es el único necesario para la siguiente solicitud de sondeo periódica programada. Por lo tanto, si estás implementando un diseño de sondeo o buscando Publicaciones por rango de id, la lógica de paginación es ligeramente más complicada. 

Ahora supongamos que hay 18 Publicaciones adicionales que coinciden. El endpoint respondería con esta respuesta inicial con una página completa de datos y un next_token para solicitar la siguiente página de datos de este período de cinco minutos. También incluiría la id de la Publicación más reciente necesaria para el siguiente intervalo de sondeo en cinco minutos.

"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }

Para recopilar todos los datos correspondientes a este período de cinco minutos, pasa el next_token en tu siguiente solicitud, junto con el mismo valor de since_id que en la solicitud anterior.

https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000&next_token=fnsih9chihsnkjbvkjbsc

"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }

Esta segunda respuesta devuelve las ocho Publicaciones restantes y no incluye next_token. Ten en cuenta que no actualizamos nuestro valor de newest_id (12300), sino que basamos nuestra siguiente solicitud con since_id en el valor de newest_id de la primera respuesta:

https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800