Enriquecimiento de datos: Empresarial

​

Introducción

Enterprise

Los enriquecimientos Empresarial son metadatos adicionales incluidos en el payload de respuesta de algunas de las API de datos. Solo están disponibles en planes de suscripción de pago.

La siguiente tabla ofrece una breve descripción de cada enriquecimiento:

Enrichment:	Description:
URL expandidas y mejoradas	Expande automáticamente las URL acortadas (p. ej., bitly) incluidas en el cuerpo de un Post y proporciona los metadatos de título y descripción HTML de la página de destino.
Objeto de reglas coincidentes	Indica qué regla o reglas hicieron match con los Posts recibidos. El objeto devuelve la etiqueta de la regla y el id de la regla en el objeto de respuesta.
Metadatos de encuesta	Indica la presencia de una encuesta en un Post, incluye la lista de opciones de la encuesta y tanto la duración de la encuesta como la hora de expiración.
Geolocalización del perfil	Datos derivados de la ubicación del perfil del usuario, incluidas las coordenadas [longitud, latitud] (cuando sea posible) y los metadatos del lugar relacionado.

​

URLs ampliadas y mejoradas

El enriquecimiento de URL ampliadas y mejoradas expande automáticamente las URL acortadas incluidas en el cuerpo de un Post y agrega la URL resultante como metadatos dentro del payload. Además, este enriquecimiento también proporciona metadatos de la página HTML a partir del title y la description de la página de destino.

Detalles importantes:

• Para resolver un enlace acortado, nuestro sistema envía solicitudes HTTP HEAD a la URL proporcionada y sigue cualquier redirección hasta llegar a la URL final. Esta URL final (NO el contenido de la página) se incluye en el payload de la respuesta.

• El enriquecimiento de URL agrega entre 5 y 10 segundos de latencia a los streams en tiempo real

• Para las solicitudes realizadas a la Full Archive Search API, los datos de enriquecimiento de URL ampliadas solo están disponibles para Posts de hasta 13 meses de antigüedad.

• El enriquecimiento de URL no está disponible para enlaces de Post (incluidos los Tweets citados), enlaces de Moments y enlaces de perfil incluidos en un Post.   

​

Carga útil de Post

El enriquecimiento de URL expandida y mejorada se encuentra dentro del objeto entities de la carga útil de Post, específicamente en el objeto entitites.urls.unwound. Proporciona los siguientes campos de metadatos:

• URL expandida - unwound.url
• Código de estado HTTP expandido - unwound.status
• Título HTML de la URL expandida - límite de 300 caracteres - unwound.title
• Descripción HTML de la URL expandida - límite de 1000 caracteres - unwound.description

Este es un ejemplo de un objeto entities con el enriquecimiento de URL:

"entities": {
    "hashtags": [

    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/HkTkwFq8UT",
        "expanded_url": "http:\/\/bit.ly\/2wYTb9y",
        "display_url": "bit.ly\/2wYTb9y",
        "unwound": {
          "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/",
          "status": 200,
          "title": "11 sitios web para aprender a programar gratis en 2017",
          "description": "Es totalmente posible aprender a programar gratis... pero ¿cuáles son los mejores recursos para lograrlo? Aquí tienes 11 sitios web para empezar."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

**Este es un ejemplo de un objeto entities que contiene un enlace a un Post no enriquecido: **

"entities": {
  "urls": [{
    "url": "https://t.co/SywNbZdDmb",
    "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728",
    "display_url": "x.com/XDevelopers/s…",
     "indices": [
        142,
        165
     ]
   }
  ]
}

​

Operadores de filtrado

Los siguientes operadores filtran y realizan una coincidencia tokenizada en los campos relacionados de los metadatos de la URL:

url:

• Ejemplo: “url:tennis”
• Coincidencia tokenizada en cualquier URL expandida que incluya la palabra tennis
• También puede usarse como filtro para incluir o excluir enlaces de un sitio web específico usando algo como “url:npr.org”

url_title:

• Ejemplo: “url_title:tennis”
• Coincidencia tokenizada en cualquier título HTML de una URL expandida que incluya la palabra tennis
• Coincide con los datos del título HTML incluidos en el payload, limitado a 300 caracteres.

url_description:

• Ejemplo: “url_description:tennis”
• Coincidencia tokenizada en cualquier descripción HTML de una URL expandida que incluya la palabra tennis
• Coincide con la descripción HTML incluida en el payload, limitada a 1000 caracteres.  

​

Códigos de estado HTTP

El enriquecimiento de URL expandida también proporciona el código de estado HTTP de la URL final que intentamos desenlazar. En casos normales, será 200. Otros valores de la serie 400 indican problemas al resolver la URL.

Se pueden devolver varios códigos de estado al intentar desenlazar una URL. Durante el proceso de desenlace de una URL, si recibimos una redirección, la seguiremos indefinidamente hasta que:

• Alcancemos un código de la serie 200 (éxito)
• Alcancemos un código que no sea de redirección (fallo)
• Se agote el tiempo porque la URL final no pudo resolverse en un plazo razonable (devuelve 408 - tiempo de espera)
• Se produzca algún tipo de excepción  

Si se produce una excepción, utilizamos el siguiente mapeo entre los motivos y los códigos de estado devueltos:

Motivo	Código de estado devuelto
Excepciones SSL	403 (Forbidden)
Desenlace no permitido por la URL	405
Tiempo de espera de socket	408 (Timeout)
Excepción de host desconocido	404 (Not Found)
Operación no admitida	404 (Not Found)
Excepción de conexión	404 (Not Found)
Argumento no válido	400 (Bad Request)
Todo lo demás	400 (Bad Request)

​

Reglas de coincidencia

El enriquecimiento de reglas de coincidencia es un objeto de metadatos que indica qué regla o reglas coincidieron con los Posts recibidos. Esto se utiliza más comúnmente con el stream de PowerTrack.

La coincidencia se realiza mediante una coincidencia exacta de los términos contenidos en una regla, analizando el contenido de la actividad con y sin puntuación. La coincidencia no distingue entre mayúsculas y minúsculas. Cuando se determine que el contenido contiene todos los términos definidos en la regla, habrá un objeto matching_rules en el nivel raíz que indique la(s) regla(s) que dieron lugar a la coincidencia.

PowerTrack

Los Posts entregados a través de PowerTrack (en tiempo real, Replay e Historical) contendrán el objeto matching_rules de la siguiente manera:

"matching_rules": [{
        "tag": null,
        "id": 907728589029646336,
        "id_str": "907728589029646336"
    }]

En PowerTrack, el objeto matching_rules refleja todas las reglas que coincidieron con el resultado dado. En otras palabras, si más de una regla coincide con un Post específico, este se entregará solo una vez, pero el elemento matching_rules incluirá todas las reglas que coincidieron.

​

Metadatos de la encuesta

Los metadatos de la encuesta son un enriquecimiento gratuito disponible en todos los productos (APIs en tiempo real e históricas) dentro de cargas útiles de formato nativo enriquecido. Los metadatos indican la presencia de una encuesta en un Post, incluyen la lista de opciones y abarcan tanto la duración de la encuesta como su tiempo de expiración. Este enriquecimiento facilita reconocer la presencia de una encuesta y permite representar correctamente un Post de encuesta para su visualización.

Detalles importantes:

• Disponible en todas las API Empresariales (PowerTrack, Replay, Search, Historical PowerTrack)
  • Nota: Para Replay y Historical PowerTrack, estos metadatos estuvieron disponibles por primera vez el 22/02/17.
• No incluye información de votos ni resultados de encuestas
• Actualmente no cuenta con compatibilidad con filtros/operadores
• Disponible solo en formato nativo enriquecido
  • El formato nativo enriquecido es una configuración controlada por el usuario que puede cambiarse en cualquier momento a través de la Consola: Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​

Carga útil de Post

Un Post con encuesta incluirá los siguientes metadatos en el objeto “entities.polls” de la carga útil:

• Un array “options” con hasta cuatro opciones que incluyen la posición (1-4) y el texto de la opción
• Fecha de expiración de la encuesta
• Duración de la encuesta

Consulta la carga útil de ejemplo a continuación para obtener más información.

​

Ejemplo de payload

A continuación, se muestra un fragmento del payload en formato nativo enriquecido que resalta los metadatos de la encuesta añadidos:

"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"La mejor respuesta"
                   },
                   {
                      "position":2,
                      "text":"La mejor respuesta"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

​

Ubicación del perfil

​

Introducción

Muchos perfiles de X incluyen información pública de ubicación proporcionada por el usuario. Estos datos se devuelven como una cadena normal en user.location (consulta el diccionario de datos del objeto User). El enriquecimiento Profile Geo añade geodatos estructurados relevantes para el valor de user.location mediante la geocodificación y la normalización de cadenas de ubicación cuando sea posible. Tanto las coordenadas de latitud/longitud como los metadatos de lugares relacionados se añaden a user.derived.locations solo cuando se incluyen como parte del payload de un Post en los productos de la API Empresarial. Estos datos están disponibles al usar el formato nativo enriquecido y se pueden filtrar con una combinación de reglas de PowerTrack.

Nota: Parte de los geodatos utilizados para crear el enriquecimiento Profile Geo provienen de GeoNames.org y son utilizados por X bajo la Licencia Creative Commons Atribución 3.0.

Los datos de Profile Geo se incluirán en las API PowerTrack, Replay, Volume Stream, Search y Historical PowerTrack de X.

​

Datos geográficos del perfil

Nombre de campo nativo enriquecido	Valor de ejemplo	Descripción
user.derived.locations.country	United States	El país del que es el usuario que creó el Post.
user.derived.locations.country_code	US	Código de país ISO‑3166 de dos letras que corresponde al país del que es el usuario que creó el Post.
user.derived.locations.locality	Birmingham	La localidad (generalmente la ciudad) de la que es el usuario que creó el Post.
user.derived.locations.region	Alabama	La región (generalmente estado/provincia) de la que es el usuario que creó el Post.
user.derived.locations.sub_region	Jefferson County	La subregión (generalmente el condado) de la que es el usuario que creó el Post.
user.derived.locations.full_name	Birmingham, Alabama, United States	El nombre completo (sin incluir la subregión) del lugar del que es el usuario que creó el Post.
User.derived.locations.geo	See Below	Una matriz que incluye un valor de latitud/longitud para una coordenada que corresponde a la ubicación de menor granularidad de la que es el usuario que creó el Post.

Las API Historical PowerTrack, Search y PowerTrack admiten el filtrado basado en los datos geográficos del perfil. Consulta la documentación del producto correspondiente para más detalles sobre qué operadores están disponibles para filtrar por datos geográficos del perfil.

​

Ejemplo de carga útil

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "Estados Unidos",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Condado de Jefferson",
                    "full_name": "Birmingham, Alabama, Estados Unidos",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

​

Limitaciones

• El enriquecimiento de Perfil Geo intenta determinar la mejor opción para el lugar geográfico descrito en la cadena de ubicación del perfil. El resultado puede no ser preciso en todos los casos debido a factores como la existencia de múltiples lugares con nombres similares o nombres ambiguos.
• Si no se proporciona un valor en el campo de ubicación del perfil de un usuario (actor.location), no intentaremos hacer una clasificación.
• Nivel de precisión: si un enriquecimiento de Perfil Geo solo puede determinarse con confianza a nivel de país o región, las geografías de nivel inferior como subRegion y locality se omitirán del payload.
• El enriquecimiento de Perfil Geo proporciona coordenadas lat/long (un único punto) que corresponden al nivel de precisión de los resultados del enriquecimiento. Estas coordenadas representan el centro geográfico de la ubicación resultante del enriquecimiento. Por ejemplo, si el nivel de precisión es el de país, esas coordenadas se establecen en el centro geográfico de ese país.
• Los operadores de PowerTrack proporcionados para las propiedades de dirección (locality/region/country/country code) son intencionalmente granulares para permitir muchas combinaciones de reglas. Al intentar dirigir una ubicación específica que comparte nombre con otra, considere combinar reglas de dirección. Por ejemplo, lo siguiente evitaría coincidencias con “San Francisco, Philippines”: profile_locality:“San Francisco” profile_region:California. Al crear reglas que apunten a campos individuales de Perfil Geo, tenga en cuenta que cada nivel adicional de granularidad limitará los resultados que vea. En algunos casos, cuando se intenta analizar data de una ciudad, es posible que prefiera basarse únicamente en una regla de región cuando esta tenga una superposición significativa con la ciudad; p. ej., la ciudad de Zúrich, Suiza puede dirigirse de manera efectiva junto con las áreas circundantes con profile_region:“Zurich”.
• Uso con Posts con Geo nativo: el enriquecimiento de Perfil Geo proporciona un tipo alternativo de geografía para un Post, distinto del valor geo nativo en el payload. Estos dos tipos de geografía pueden combinarse para capturar todos los posibles Posts relacionados con un área determinada (según la geodata disponible), aunque no son conceptualmente equivalentes.