数据增强：Enterprise

​

介绍

Enterprise

Enterprise 增强功能是某些数据 API 响应负载中附加的元数据，仅在付费订阅计划中提供。

下表对每种增强功能作简要说明：

增强功能：	说明：
扩展与增强的 URL	自动展开包含在 Post 正文中的短链接（例如 bitly），并从目标页面提取 HTML 标题与描述元数据。
匹配规则对象	指示收到的 Posts 匹配了哪些规则。该对象在响应中返回规则标签和规则 id。
投票元数据	标记 Post 中是否包含投票，包含投票选项列表，以及投票时长与到期时间。
个人资料地理信息	基于用户个人资料推导的位置信息，包括（在可能情况下）经度、纬度坐标及相关地点元数据。

​

扩展与增强的 URL

“扩展与增强的 URL”富化会自动展开包含在 Post 正文中的短链接，并将展开后的 URL 作为元数据包含在有效负载中。此外，此富化还会提供目标页面 title 和 description 的 HTML 页面元数据。

重要细节：

• 为解析短链接，我们的系统会向提供的 URL 发送 HTTP HEAD 请求，并跟随所有重定向直至抵达最终 URL。随后将在响应有效负载中包含该最终 URL（而非页面内容本身）。

• URL 富化会为实时 stream 增加约 5–10 秒的延迟

• 对 Full Archive Search API 发起的请求，扩展 URL 富化数据仅适用于 13 个月内的 Posts。

• URL 富化不适用于 Post 链接（包括引用 Tweet）、Moments 链接，以及包含在 Post 中的个人资料链接。   

​

Post 负载

Expanded 和 Enhanced URL 丰富信息位于 Post 负载的 entities 对象中——具体是在 entitites.urls.unwound 对象内。它提供以下 metadata 字段：

• 展开后的 URL - unwound.url
• 展开后的 HTTP 状态 - unwound.status
• 展开后的 URL HTML 标题（最多 300 个字符）- unwound.title
• 展开后的 URL HTML 描述（最多 1000 个字符）- unwound.description

以下是一个包含 URL 丰富信息的 entities 对象示例：

"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": "2017年11个免费学编程的网站",
          "description": "完全可以免费学习编程...但哪些是最好的资源呢？这里推荐11个可以开始学习的网站。"
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

以下示例展示了一个包含未富化 Post 链接的 entities 对象：

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

​

过滤运算符

以下运算符会基于 URL metadata 的相关 fields 进行过滤，并提供分词匹配：

url:

• 示例：“url:tennis”
• 对任何包含单词 tennis 的 Expanded URL 进行分词匹配
• 也可作为过滤条件，用于包含或排除来自特定网站的链接，例如“url:npr.org”

url_title:

• 示例：“url_title:tennis”
• 对任何 Expanded URL 的 HTML title 中包含单词 tennis 的情况进行分词匹配
• 匹配负载（payload）中包含的 HTML title data，长度上限为 300 个字符。

url_description:

• 示例：“url_description:tennis”
• 对任何 Expanded URL 的 HTML description 中包含单词 tennis 的情况进行分词匹配
• 匹配负载（payload）中包含的 HTML description，长度上限为 1000 个字符。  

​

HTTP 状态码

扩展的 URL 增强功能还会提供我们尝试解展开的最终 URL 的 HTTP 状态码。正常情况下为 200。其他 4xx 系列的值表示解析该 URL 时出现问题。

在尝试展开 URL 时，可能会返回各种状态码。在展开过程中，如果遇到重定向，我们会一直跟随，直到出现以下任一情况：

• 返回 2xx 系列代码（成功）
• 返回非重定向系列代码（失败）
• 因在合理时间内无法解析最终 URL 而超时（返回 408 — 超时）
• 遇到某种异常  

如果遇到异常，我们会按以下原因与返回状态码进行映射：

原因	返回的状态码
SSL 异常	403（Forbidden）
不允许按该 URL 展开	405
套接字超时	408（Timeout）
未知主机异常	404（Not Found）
不支持的操作	404（Not Found）
连接异常	404（Not Found）
非法参数	400（Bad Request）
其他情况	400（Bad Request）

​

匹配规则

“匹配规则”丰富信息是一个 metadata 对象，用于指示接收到的 Post 是由哪些规则匹配到的。此功能最常与 PowerTrack stream 搭配使用。

匹配通过对规则中包含的词项进行精确匹配来完成，会在含标点与不含标点两种情况下扫描活动内容。匹配不区分大小写。当内容被确认包含规则中定义的全部词项时，根级会出现一个 matching_rules 对象，指明触发匹配的规则。

PowerTrack

通过 PowerTrack（实时、Replay 和 Historical）传递的 Post 将包含如下的 matching_rules 对象：

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

在 PowerTrack 中，matching_rules 对象反映与给定结果匹配的所有规则。换句话说，即使有多个规则匹配某个特定的 Post，它也只会被投递一次，但 matching_rules 元素会包含所有匹配的规则。

​

投票元数据

投票元数据是在所有产品（实时与历史 API）中可用的免费增强内容，作为增强的原生格式负载提供。该元数据标示 Post 中是否包含投票，提供投票选项列表，并包含投票的持续时间与到期时间。此增强内容便于识别投票的存在，并支持对含投票的 Post 进行正确渲染以供展示。

重要细节：

• 适用于所有 Enterprise 级 API（PowerTrack、Replay、Search、Historical PowerTrack）
  • 注意： 对于 Replay 和 Historical PowerTrack，此 metadata 首次于 2017/02/22 提供。
• 不包含投票信息或投票结果
• 目前不支持筛选器/运算符
• 仅提供 enriched native format（增强型原生格式）
  • Enriched native format 是一项用户可控设置，可随时通过 Console 更改：Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​

Post 负载

投票类 Post 的负载中，“entities.polls”对象包含以下 metadata：

• 一个“options”数组，最多包含四个选项，包含位置（1-4）和选项文本
• 投票到期日期
• 投票持续时间

有关更多信息，请参阅下方的示例负载。

​

示例载荷

下面是一个增强后的原生格式载荷片段，突出展示了新增的投票 metadata：

"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"更好的答案"
                   },
                   {
                      "position":2,
                      "text":"最佳答案"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

​

个人资料地理信息

​

介绍

许多 X 用户资料包含由用户提供的公开位置信息。该数据以普通字符串形式返回在 user.location 字段中（参见 用户对象数据字典）。Profile Geo Enrichment 会在可行时对位置字符串进行地理编码与规范化，从而为 user.location 的取值补充相关的结构化地理数据。仅当这些信息作为 Enterprise API 产品中 Post 负载的一部分包含时，纬度/经度坐标及相关地点 metadata 才会添加到 user.derived.locations 中。使用 enriched native 格式 时可获取该数据，并可结合 PowerTrack 规则进行过滤。

注意： 用于创建 Profile Geo Enrichment 的部分支撑地理数据来自 GeoNames.org，X 根据 Creative Commons Attribution 3.0 License 使用这些数据。

Profile Geo 数据将包含在 X 的 PowerTrack、Replay、Volume Stream、Search 和 Historical PowerTrack API 中。

​

个人资料地理数据

增强的原生字段名称	示例值	描述
user.derived.locations.country	United States	创建该 Post 的用户的国家。
user.derived.locations.country_code	US	与创建该 Post 的用户所在国家对应的两字母 ISO-3166 国家代码。
user.derived.locations.locality	Birmingham	创建该 Post 的用户的所在地（通常为城市）。
user.derived.locations.region	Alabama	创建该 Post 的用户的地区（通常为州/省）。
user.derived.locations.sub_region	Jefferson County	创建该 Post 的用户的次级地区（通常为县/郡）。
user.derived.locations.full_name	Birmingham, Alabama, United States	创建该 Post 的用户所在地的全称（不含次级地区）。
user.derived.locations.geo	See Below	一个数组，其中 includes 为与创建该 Post 的用户的最细粒度所在地相对应的坐标提供的纬度/经度值。

Historical PowerTrack、Search 和 PowerTrack API 支持基于个人资料地理数据进行过滤。有关可用于个人资料地理数据过滤的运算符的详细信息，请参阅相应的产品文档。

​

示例载荷

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "美国",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Jefferson County",
                    "full_name": "伯明翰，阿拉巴马州，美国",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

​

限制

• Profile Geo 丰富化会尝试为用户资料位置字符串中描述的地理地点确定最合适的匹配。但由于可能存在同名地点或名称歧义等因素，结果未必在所有情况下都准确。
• 如果用户的资料位置字段（actor.location）未提供值，我们将不尝试进行分类。
• 精度级别：如果 Profile Geo 丰富化只能在国家或区域层级达到可信的判定，则负载中将省略更低层级的地理信息，如下级区域（subRegion）和地方（locality）。
• Profile Geo 丰富化会提供与其结果精度级别相对应的经纬度坐标（单一点）。这些坐标表示丰富化结果位置的地理中心。例如，如果精度级别为国家级，则这些坐标将设为该国家的地理中心。
• 为地址属性（locality/region/country/country code）提供的 PowerTrack 运算符刻意设计为细粒度，以便支持多种规则组合。当尝试定位与其他地点同名的特定位置时，请考虑组合地址规则。例如，以下组合可避免匹配“San Francisco, Philippines”：profile_locality:“San Francisco” profile_region:California。构建针对单个 Profile Geo 字段的规则时，请注意，每提升一级粒度都会缩小可见结果。在某些情况下，当关注某个城市的数据时，您可能只需依赖区域规则（当该区域与该城市有显著重叠时），例如瑞士的苏黎世可通过 profile_region:“Zurich” 有效定位，并覆盖周边区域。
• 与原生地理 Post 配合使用：Profile Geo 丰富化为 Post 提供一种不同于负载中原生地理值的替代地理类型。两者可结合使用，以基于可用地理数据捕获与某一地区相关的所有可能的 Post，但二者在概念上并不等同。