Cómo obtener Publicaciones históricas con el endpoint de búsqueda en el archivo completo de la v2

Introducción

Los endpoints de Search Posts en el entorno de la v2 te permiten recibir Publicaciones relacionadas con temas de interés, basadas en una consulta de búsqueda que tú defines. 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 Publicaciones 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 que puede buscar en todo el archivo de Publicaciones que se remonta a marzo de 2006.

Puedes ver toda nuestra oferta de búsqueda en nuestra página de descripción general de búsqueda.

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

Este tutorial proporciona una guía paso a paso para investigadores que deseen usar el endpoint de búsqueda de archivo completo para buscar en todo el historial de datos públicos de X. También mostrará las diferentes formas de crear un conjunto de datos, como por ejemplo recuperar Publicaciones con etiqueta geográfica, y cómo recorrer mediante paginación las Publicaciones disponibles para una consulta.

Requisitos previos

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

Conectar una App al proyecto académico

Una vez que se apruebe tu acceso al producto Academic Research, verás tu proyecto académico en la Consola de desarrollador. En la sección “Apps”, haz clic en “Add App” para conectar tu X App al proyecto.

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

O puedes crear una nueva App, asignarle un nombre y hacer clic en “Complete” para conectar una nueva App a tu Academic Project.

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

Ten en cuenta lo siguiente

Las claves en la captura de pantalla anterior están ocultas, pero en tu propia Consola de desarrollador podrás ver los valores reales de la API Key, la API Secret Key y el Bearer Token. Guarda estas claves y el Bearer Token porque las necesitarás para llamar al endpoint de búsqueda en el archivo completo.

Conectarse al endpoint de búsqueda en el archivo completo

El siguiente comando cURL muestra cómo puedes obtener Publicaciones históricas de la cuenta @XDevelopers. Reemplaza $BEARER_TOKEN con tu propio Bearer Token, pega la solicitud completa en tu terminal y pulsa la tecla “Intro”.

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

Verás el JSON de la respuesta.

De forma predeterminada, solo se devolverán las 10 Publicaciones más recientes. Si quieres más de 10 Publicaciones por solicitud, puedes usar el parámetro max_results y configurarlo con un máximo de 500 Publicaciones 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 puedes ver en los ejemplos de llamadas anteriores, usando el parámetro query puedes especificar los datos que quieres buscar. Por ejemplo, si quisieras obtener todas las Publicaciones que contengan la palabra covid o la palabra coronavirus, puedes usar el operador OR entre paréntesis, y tu consulta podría 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 quieres todas las Publicaciones que contengan la palabra covid19 y que no sean republicaciones, puedes usar el operador is:retweet con el operador lógico NOT (representado por -), de modo que tu consulta podría ser covid19 -is:retweet y tu 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 que son compatibles con el endpoint de búsqueda en todo el archivo.

Uso de los parámetros start_time y end_time para obtener Publicaciones históricas

Al usar el endpoint de búsqueda de archivo completo, de forma predeterminada se devolverán Publicaciones de los últimos 30 días. Si quieres obtener Publicaciones de hace más de 30 días, puedes usar los parámetros start_time y end_time en la 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 quieres obtener todas las Publicaciones de la cuenta de XDevelopers para el mes de diciembre de 2020, tu 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 Publicaciones históricas con geoetiquetas

Las Publicaciones con geoetiquetas son aquellas que tienen información geográfica asociada, como ciudad, estado, país, etc.

Uso del operador has:geo

Si deseas obtener Publicaciones que tengan datos de geolocalización, puedes usar el operador has:geo. Por ejemplo, la siguiente solicitud cURL recuperará solo aquellas Publicaciones de la cuenta @XDevelopers que tienen datos de geolocalización:

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, puedes limitar las Publicaciones que tienen datos de geolocalización a un país específico usando el operador place_country. El siguiente comando cURL obtendrá todas las Publicaciones del handle @XDevelopers de Estados Unidos:

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

El país se especifica más arriba mediante el código ISO alfa-2 de dos letras. Los códigos ISO válidos se pueden encontrar aquí.

Obtener más de 500 Publicaciones históricas usando el next_token

Como se mencionó anteriormente, de forma predeterminada solo puedes obtener hasta 500 Publicaciones por solicitud para una consulta al endpoint de búsqueda de archivo completo. Si hay más de 500 Publicaciones disponibles para tu consulta, tu respuesta JSON incluirá un next_token que puedes añadir a tu llamada a la API para obtener las siguientes Publicaciones disponibles para esa consulta. Este next_token está disponible en el objeto meta de tu respuesta JSON, que se ve de la siguiente manera:

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

Por lo tanto, para obtener las siguientes Publicaciones disponibles, utiliza el valor de next_token de este objeto meta y úsalo como valor de next_token en tu llamada a la API al endpoint de búsqueda de archivo completo, como se muestra a continuación (usarás tu propio Bearer Token y el valor de Next Token que obtengas en tu llamada de API anterior).

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 esta manera, puedes seguir verificando si hay un next_token disponible y, si aún no has alcanzado la cantidad de Publicaciones que deseas recopilar, puedes seguir llamando al endpoint de archivo completo con el nuevo next_token en cada solicitud.

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

Recursos adicionales

• Referencia de la API del endpoint de búsqueda en el archivo completo
• Aprende los conceptos básicos para crear una consulta de búsqueda