Skip to main content

​
Standard v1.1 en comparación con X API v2

Si has estado trabajando con la búsqueda de Publicaciones de la v1.1, el objetivo de esta guía es ayudarte a comprender las similitudes y diferencias entre el endpoint estándar de búsqueda y el endpoint de búsqueda de Publicaciones de X API v2.
  • Similitudes
    • Contexto de usuario OAuth 1.0a y OAuth 2.0 solo para App
    • Compatibilidad con el historial de edición de Publicaciones y metadatos. 
  • Diferencias
    • URLs de los endpoints
    • Requisitos de App y Proyecto
    • Formato de los datos de respuesta
    • Parámetros de la solicitud
    • Nuevos operadores de consulta
    • Precedencia de los operadores AND/OR 

​
Similitudes

Autenticación OAuth 1.0a con contexto de usuario y OAuth 2.0 App-Only El endpoint search/posts de v1.1 y el endpoint de búsqueda reciente de X API v2 admiten tanto OAuth 1.0a User Context como OAuth 2.0 App-Only.  Por lo tanto, si antes utilizabas el endpoint estándar de búsqueda de v1.1, puedes seguir usando el mismo método de autenticación si migras a la versión de X API v2.  Dependiendo de la biblioteca/paquete de autenticación que elijas, la autenticación App-Only probablemente sea la forma más sencilla de comenzar y se puede configurar con un encabezado sencillo en la solicitud. Para aprender a generar un App Access Token, consulta esta guía de OAuth 2.0 App-Only.  Si deseas aprovechar la posibilidad de obtener métricas privadas o de publicidad con el endpoint de X API v2, deberás usar OAuth 1.0a User Context y pasar los tokens de acceso de usuario asociados al usuario que publicó la Publicación para la cual deseas obtener métricas.  Compatibilidad con el historial de edición de Publicaciones y metadatos Ambas versiones proporcionan metadatos que describen cualquier historial de edición. Consulta las Referencias de la API de búsqueda y la página de conceptos básicos sobre la edición de Publicaciones para obtener más detalles. 

​
Diferencias

URLs de endpoints Requisitos de App y Project Los endpoints de X API v2 requieren que utilices credenciales de una developer App que esté asociada a un Project al autenticar tus solicitudes. Todos los endpoints de X API v1.1 pueden usar credenciales de Apps independientes o de Apps asociadas con un Project.  Formato de datos de la respuesta Una de las mayores diferencias entre las versiones de endpoints estándar v1.1 y X API v2 es cómo seleccionas qué campos se devuelven en tu payload. Para los endpoints estándar, recibes muchos de los campos de la respuesta de forma predeterminada y luego tienes la opción de usar parámetros para identificar qué campos o conjuntos de campos deben devolverse en el payload. La versión de X API v2 solo entrega el id de la Publicación y el campo de texto de forma predeterminada. Para solicitar campos u objetos adicionales, deberás usar los parámetros fields y expansions. Cualquier campo de Publicación que solicites desde estos endpoints se devolverá en el objeto principal de la Publicación. Cualquier objeto y campo expandido de usuario, medio, encuesta o lugar se devolverá en un objeto includes dentro de tu respuesta. Luego podrás relacionar cualquier objeto expandido con el objeto de la Publicación haciendo coincidir los id que se encuentran tanto en la Publicación como en el objeto expandido.  Te recomendamos leer más sobre estos nuevos parámetros en sus respectivas guías o leyendo nuestra guía sobre cómo usar fields y expansions.  También hemos preparado una guía de migración de formato de datos que puede ayudarte a mapear los campos estándar v1.1 a los campos más recientes de v2. Esta guía también te proporcionará el parámetro específico de expansión y de campo que deberás pasar con tu solicitud v2 para devolver campos específicos.    Además de los cambios en cómo solicitas determinados campos, X API v2 también introduce nuevos diseños JSON para los objetos devueltos por las API, incluidos los objetos de Publicación y de usuario.
  • En el nivel raíz de JSON, los endpoints estándar devuelven objetos de Publicación en un array statuses, mientras que X API v2 devuelve un array data. 
  • En lugar de hacer referencia a “statuses” Retweeted y Quoted, el JSON de X API v2 hace referencia a Tweets Retweeted y Quoted. Muchos campos heredados y obsoletos, como contributors y user.translator_type, se están eliminando. 
  • En lugar de usar tanto favorites (en el objeto de la Publicación) como favourites (en el objeto de usuario), X API v2 utiliza el término like. 
  • X está adoptando la convención de que los valores JSON sin valor (por ejemplo, null) no se escriben en el payload. Los atributos de Publicación y de usuario solo se incluyen si tienen valores distintos de null.   
También hemos incorporado un nuevo conjunto de campos al objeto de Publicación, incluidos los siguientes:
  • Un campo conversation_id
  • Dos nuevos campos de annotations, incluidos context y entities
  • Varios campos nuevos de metrics 
  • Un nuevo campo reply_setting, que te muestra quién puede responder a una Publicación determinada

​
Parámetros de la solicitud

Los siguientes parámetros de solicitud estándar v1.1 tienen equivalentes en X API v2:
Búsqueda estándar v1.1Search Posts v2
qquery
start_time (YYYY-MM-DDTHH:mm:ssZ)
until (YYYY-MM-DD)end_time (YYYY-MM-DDTHH:mm:ssZ)
since_idsince_id
max_iduntil_id
countmax_results
Response provides search_metadata.next_resultsnext_token
También hay un conjunto de parámetros estándar de búsqueda de Publicaciones que no se admiten en X API v2:
Parámetro estándar v1.1Detalles
geocodeSearch Posts admite operadores geográficos para consultas basadas en ubicación.
localeEn la búsqueda estándar, se utilizaba para especificar el idioma de la consulta, pero nunca se implementó por completo.
langLos endpoints de Search Posts proporcionan un operador de consulta lang para hacer coincidencias en idiomas de interés.
include_entitiesLas entidades de la Publicación siempre se incluyen.
result_typeLos endpoints de Search Posts devuelven todas las Publicaciones que coinciden, independientemente del nivel de interacción.
extendedX API v2 está diseñada desde cero para admitir Publicaciones de hasta 280 caracteres. En v2, no existe el concepto de Publicaciones «extendidas».
Este es un ejemplo de solicitud que muestra la diferencia entre una solicitud estándar y una solicitud Search Posts:
Standard v1.1X API v2
https://api.x.com/1.1/search/tweets.json?q=snow&count=50https://api.x.com/2/tweets/search/recent?query=snow&max_results=50
Ambas solicitudes devolverán las 50 Publicaciones más recientes que contienen la palabra clave «snow». La solicitud v2 devolverá los campos predeterminados id y text de las Publicaciones coincidentes. Este es un ejemplo de cómo especificar campos adicionales de Publicaciones y de usuario para incluir en la carga útil JSON:
X API v2
https://api.x.com/2/tweets/search/recent?query=snow&max_results=50&tweet.fields=id,created_at,author_id,text,source,entities,attachments&user.fields=id,name,username,description
Nuevos operadores de consulta Search Posts introduce nuevos operadores para admitir dos funciones nuevas de X API v2: 
  • Conversation IDs - A medida que se desarrollan las conversaciones en X, habrá un ID de conversación disponible para marcar las Publicaciones que forman parte de la conversación. Todas las Publicaciones de la conversación tendrán su conversation_id establecido en el ID de la Publicación que la inició. 
    • conversation_id:
  • X Annotations proporcionan información contextual sobre las Publicaciones e incluyen anotaciones de entidad y de contexto. Las entidades se componen de personas, lugares, productos y organizaciones. Los contextos son dominios o temas de los que forman parte las entidades que aparecen. Por ejemplo, las personas mencionadas en una Publicación pueden tener un contexto que indique si son atletas, actores o políticos.  
    • context: coincide con Publicaciones que han sido anotadas con un contexto de interés. 
    • entity: coincide con Publicaciones que han sido anotadas con una entidad de interés.   

​
Precedencia de los operadores AND / OR

El componente básico para crear consultas de búsqueda es el uso de agrupaciones lógicas con OR y AND. La API de búsqueda estándar aplica primero los OR y después los AND, mientras que los endpoints de Search Posts (así como las versiones premium y enterprise) aplican primero los AND y después los OR. Esta diferencia es crítica al convertir consultas entre ambas.  Por ejemplo, con la búsqueda estándar, si quisieras obtener Publicaciones con la palabra clave ‘storm’ que mencionen la palabra ‘colorado’ o el hashtag #COwx, podrías hacerlo con la siguiente consulta de búsqueda: storm #COwx OR colorado Con la precedencia de operadores de Search Posts, los AND se aplican antes que los OR. Así que la consulta anterior es equivalente a:  (storm #COwx) OR colorado Sin embargo, la regla anterior devolvería cualquier Publicación que mencione ‘Colorado’, independientemente de si la Publicación menciona ‘storm’ o el hashtag #COwx. Además, también devolvería Publicaciones que mencionen tanto la palabra clave ‘storm’ como el hashtag #COwx.  Para que la consulta se comporte como se pretendía originalmente, las cláusulas OR deben agruparse. La conversión de la consulta estándar original a Search Posts sería: storm (#COwx OR colorado) Estas dos reglas tienen comportamientos de coincidencia muy diferentes. Para el mes de octubre de 2019, la regla original coincide con más de 1.175.000 Publicaciones, mientras que la regla correctamente convertida coincide con alrededor de 5.600 Publicaciones. Asegúrate de prestar atención a tus AND y OR, y usa paréntesis cuando sea necesario. 

​
Solicitudes cURL

La siguiente sección muestra solicitudes cURL para el endpoint estándar v1.1 y su endpoint equivalente en v2. Las solicitudes se realizan usando [OAuth 2.0 App-Only](https://developer.x.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token). Para poder ejecutar las siguientes solicitudes cURL, deberás reemplazar ACCESS_TOKEN en el encabezado de autorización por el token de acceso de tu App. Para los endpoints de v2, el token de acceso de tu App debe pertenecer a una App de desarrollador dentro de un Proyecto.  El payload de la respuesta devuelta por el endpoint v1.1 será diferente del payload de la respuesta devuelta por el endpoint v2. Con v2, la respuesta incluirá los campos predeterminados, así como cualquier otro campo solicitado con los parámetros fields y expansions. Puedes usar estos parámetros para solicitar que se devuelva un conjunto diferente de campos. Estándar v1.1 GET search/tweets → v2 GET tweets/search/recent
cURL (v1.1)
curl --request GET \
  --url 'https://api.x.com/1.1/search/tweets.json?q=from%3AXDevelopers%20-is%3Aretweet&count=100' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'
Próximos pasos Consulta nuestra guía de inicio rápido de búsqueda reciente de X API v2 Revisa la referencia de la API para búsqueda reciente Consulta algo de código de ejemplo para estos endpoints Guía paso a paso para hacer tu primera solicitud a la búsqueda reciente