Campos

Los endpoints de la X API v2 cuentan con un conjunto de parámetros llamados campos (fields), que te permiten seleccionar únicamente los datos que necesitas de cada objeto en la respuesta del endpoint.

De forma predeterminada, el objeto Post solo devuelve los campos id y text y, para los Posts creados desde el 29 de septiembre de 2022, el campo edit_history_tweet_ids. Si necesitas la fecha de creación del Post o las métricas públicas, deberás usar el parámetro tweet.fields para solicitarlas. Esto ofrece un mayor grado de personalización al permitirte pedir solo los campos necesarios según tu caso de uso. Por ejemplo, incluirías esta cadena de consulta en tu solicitud:

?tweet.fields=created_at,public_metrics

Cada objeto tiene su propio parámetro para solicitar específicamente los campos asociados con ese objeto. Estos son los diferentes parámetros de campos disponibles actualmente:

• Post → tweet.fields
• User → user.fields
• Media → media.fields
• Poll → poll.fields
• Place → place.fields

Cuando uses un endpoint que devuelve principalmente un objeto en particular, utiliza el parámetro de campos correspondiente y especifica los campos deseados en una lista separada por comas como valor de ese parámetro para obtener esos campos en la respuesta.

​

Ejemplo

Si utiliza el endpoint GET /tweets/search/recent, recibirá principalmente objetos Tweet en esa respuesta. Sin especificar ningún parámetro fields, solo recibirá los valores predeterminados, id y text. Si le interesa recibir las métricas públicas de los Posts que se devuelven en la respuesta, debe incluir el parámetro tweet.fields en su solicitud, con public_metrics como valor.

Esta solicitud tendría el siguiente aspecto. Si desea usarla, asegúrese de reemplazar $BEARER_TOKEN por su Bearer Token y envíela usando su herramienta de línea de comandos.

curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

Si envías esta solicitud en tu terminal, cada uno de los Posts que se devuelvan incluirá los siguientes fields:

{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "¿Ves 👀 nuestra nueva configuración de Tweet?\n\nQueremos saber cómo y por qué usarías una función como esta en la API. Consulta los detalles y cuéntanos qué opinas👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}

Si desea recuperar un conjunto de campos de un objeto secundario asociado al objeto principal que devuelve un endpoint, deberá incluir un parámetro adicional expansions. Por ejemplo, si utiliza el mismo endpoint GET search/tweets/recent que antes y desea obtener la descripción del perfil del autor, deberá enviar expansions=author_id y user.fields=description con su solicitud. A continuación se muestra un ejemplo de cómo podría verse. Si desea probar esta solicitud, asegúrese de reemplazar $BEARER_TOKEN por su Bearer Token antes de pegarla en su herramienta de línea de comandos.

  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'

Si especificas esto en la solicitud, cada Post que se entregue tendrá los siguientes fields, y los fields predeterminados y especificados del objeto de usuario se devolverán dentro de includes. El objeto de usuario puede vincularse al/los Post correspondiente(s) haciendo coincidir los tweet.author_id y users.id fields.

{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "¿Ya viste 👀 nuestra nueva configuración de Tweet?\n\nQueremos saber cómo y por qué usarías una función como esta en la API. Consulta los detalles y cuéntanos qué piensas👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "La voz del equipo de #TwitterDev y tu fuente oficial de actualizaciones, noticias y eventos relacionados con la #TwitterAPI.",
        "name": "Twitter Dev"
      }
    ]
  }
}

Tenga en cuenta que no puede solicitar subcampos específicos (por ejemplo, public_metrics.retweet_count). Todos los subcampos se devolverán cuando se especifique el campo de nivel superior (public_metrics). Hemos enumerado todos los posibles fields que puede solicitar en la tabla de parámetros de la página de referencia de la API de cada endpoint.

La lista completa de fields se encuentra en el modelo de objeto. Para obtener campos de un objeto que no sea el recurso principal de ese endpoint, utiliza el parámetro expansions junto con fields.