Obtención de Posts históricos con el endpoint de búsqueda de archivo completo de v2

​

Introducción

Los endpoints de búsqueda de Posts en v2 le permiten recibir Posts relacionados con temas de interés, basados en una query de búsqueda que usted genere. Contamos con dos endpoints diferentes disponibles con v2 Search Posts: la búsqueda reciente, que está disponible para todos los desarrolladores con una cuenta aprobada y puede buscar Posts de hasta siete días de antigüedad, y la búsqueda de archivo completo, que solo está disponible para investigadores aprobados para el Academic Research product track, y permite buscar en todo el archivo de Posts que se remonta a marzo de 2006.

Puede consultar nuestra oferta completa de búsqueda en nuestra página de descripción general de búsqueda.

Estos endpoints de Search Posts cubren uno de los casos de uso más comunes para investigadores académicos, quienes podrían usarlos para estudios longitudinales o para analizar un tema o evento pasado.

Este tutorial proporciona una guía paso a paso para investigadores que desean usar el endpoint de búsqueda de archivo completo para buscar el historial completo de data pública de X. También mostrará diferentes formas de crear un conjunto de datos, como recuperar Posts con etiquetas geográficas, y cómo paginar los Posts disponibles para una query.

​

Requisitos previos

Actualmente, este endpoint solo está disponible como parte del Academic Research product track. Para usar este endpoint, debes solicitar acceso. Obtén más información sobre la solicitud y los requisitos de este track.

​

Conectar una App al proyecto académico

Una vez que te aprueben para usar el producto Academic Research, verás tu Project académico en el portal de desarrolladores. En la sección “Projects and Apps”, haz clic en “Add App” para conectar tu X App al Project.

Luego, puedes elegir una App existente y conectarla a tu Project (como se muestra a continuación).

O puedes crear una nueva App, darle un nombre y hacer clic en “Complete” para conectar una nueva App a tu Project académico.

Esto te proporcionará tus API Keys y Bearer Token, que luego podrás usar para conectarte al endpoint de búsqueda de archivo completo.

Ten en cuenta

Las keys en la captura de pantalla anterior están ocultas, pero en tu propio portal de desarrolladores podrás ver los valores reales de la API Key, la Clave secreta de la API y el Bearer Token. Guarda estas keys y el Bearer Token porque los necesitarás para invocar el endpoint de búsqueda de archivo completo.

​

Conexión con el endpoint de búsqueda de archivo completo

El siguiente comando cURL muestra cómo obtener Posts históricos de la cuenta @XDevelopers. Sustituye $BEARER_TOKEN por tu propio Bearer Token, pega la solicitud completa en tu terminal y pulsa «Return».

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'

Verás el JSON de respuesta.

De forma predeterminada, solo se devolverán los 10 Posts más recientes. Si deseas más de 10 Posts por solicitud, puedes usar el parámetro max_results y configurarlo en un máximo de 500 Posts por solicitud, como se muestra a continuación:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Creación de consultas

Como se muestra en los ejemplos de llamadas anteriores, usando el parámetro query puedes especificar los datos que deseas buscar. Por ejemplo, si quisieras obtener todos los Posts que contengan la palabra covid o la palabra coronavirus, puedes usar el operador OR entre paréntesis, y tu query puede ser (covid OR coronavirus) y, por lo tanto, tu llamada a la API tendrá el siguiente aspecto:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

De manera similar, si desea todos los Posts que contengan la palabra covid19 y que no sean Retweets, puede usar el operador is:retweet con la negación lógica (representada por -), de modo que su query puede ser covid19 -is:retweet y su llamada a la API será:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'

Consulta esta guía para ver la lista completa de operadores admitidos en el endpoint de búsqueda de archivo completo.

​

Uso de los parámetros start_time y end_time para obtener Posts históricos

Al usar el endpoint de búsqueda de archivo completo, de forma predeterminada se devolverán Posts de los últimos 30 días. Si desea obtener Posts anteriores a 30 días, puede usar los parámetros start_time y end_time en su llamada a la API. Estos parámetros deben estar en un formato de fecha y hora RFC3339 válido, por ejemplo, 2020-12-21T13:00:00.00Z. Así, si desea obtener todos los Posts de la cuenta XDevelopers correspondientes al mes de diciembre de 2020, su llamada a la API será:

curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'

​

Obtención de Posts históricos con etiquetas geográficas

Los Posts con etiquetas geográficas son aquellos que tienen información de ubicación asociada, como ciudad, estado, país, etc.

​

Uso del operador has:geo

Si desea obtener Posts que contengan data geográfica, puede usar el operador has:geo. Por ejemplo, la siguiente solicitud de cURL recuperará solo aquellos Posts del handle @XDevelopers que tienen data geográfica:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

Uso del operador place_country

De manera similar, puede limitar los Posts que tienen datos geográficos a un país específico utilizando el operador place_country. El siguiente comando cURL obtendrá todos los Posts de la cuenta @XDevelopers de Estados Unidos:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

El país se especifica arriba mediante el código de dos letras ISO (alfa‑2). Puedes encontrar los códigos ISO válidos aquí.

​

Obtener más de 500 Posts históricos usando el next_token

Como se mencionó anteriormente, de forma predeterminada solo puede obtener hasta 500 Posts por solicitud para una query al endpoint de búsqueda de archivo completo. Si hay más de 500 Posts disponibles para su query, su respuesta JSON incluirá un next_token que puede adjuntar a su llamada a la API para obtener los siguientes Posts disponibles para esta query. Este next_token está disponible en el objeto meta de su respuesta JSON, que se ve algo así:

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

Por lo tanto, para obtener los siguientes Posts disponibles, use el valor de next_token de este objeto meta y utilícelo como valor de next_token en su llamada a la API al endpoint de búsqueda de archivo completo, como se muestra a continuación (usará su propio Bearer Token y el valor de Next Token que obtuvo en su llamada anterior a la API).

curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'

De este modo, puedes seguir comprobando si hay un next_token disponible y, si aún no has alcanzado la cantidad de Posts que deseas recopilar, puedes continuar llamando al endpoint de archivo completo con el nuevo next_token en cada solicitud. Ten en cuenta que el endpoint de búsqueda de archivo completo computa para tu total de Post cap, es decir, el número de Posts por mes que puedes obtener de la X API por Project. Por lo tanto, revisa la lógica de tu código al paginar los resultados para asegurarte de no agotar inadvertidamente tu Post cap.

A continuación, encontrarás algunos recursos que pueden ayudarte al usar el endpoint de búsqueda de archivo completo. Nos encantaría conocer tus comentarios. Comunícate con nosotros en @XDevelopers o en nuestros foros de la comunidad si tienes preguntas sobre este endpoint.

​

Recursos adicionales

• Referencia del API del endpoint de búsqueda de archivo completo
• Aprende los conceptos básicos para crear una query de búsqueda