数据增强：企业版

​

介绍

Enterprise

Enterprise 增强是包含在某些数据 API 响应负载中的附加元数据。仅适用于付费订阅方案。

下表对每种增强提供了简要说明：

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

​

扩展与增强的 URL

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

重要细节：

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

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

• 对 Full Archive Search API 发起的请求，展开的 URL 富化数据仅适用于发布时间在 13 个月以内的 Post。

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

​

Post 负载

扩展与增强的 URL 增益信息位于 Post 负载的 entities 对象中——具体在 entitites.urls.unwound 对象内。它提供以下元数据字段：

• 展开后的 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": [

    ]
  },

**这是一个 entities 对象的示例，其中包含未富化的 Post 链接： **

"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 元数据的相关字段进行过滤，并执行分词匹配：

url:

• 示例：“url:tennis”
• 对任何包含单词 tennis 的展开后 URL（Expanded URL）进行分词匹配
• 也可用作过滤条件，通过类似“url:npr.org”的写法包含或排除来自特定网站的链接

url_title:

• 示例：“url_title:tennis”
• 对任何包含单词 tennis 的展开后 URL 的 HTML 标题进行分词匹配
• 匹配响应负载（payload）中包含的 HTML 标题数据，长度上限为 300 个字符。

url_description:

• 示例：“url_description:tennis”
• 对任何包含单词 tennis 的展开后 URL 的 HTML 描述进行分词匹配
• 匹配响应负载（payload）中包含的 HTML 描述，长度上限为 1000 个字符。  

​

HTTP 状态码

扩展的 URL 丰富化功能还会提供我们尝试展开（unwind）的最终 URL 的 HTTP 状态码。正常情况下，该值为 200。其他 400 段的状态码表示解析该 URL 时出现问题。

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

• 返回 200 段状态码（成功）
• 返回非重定向段状态码（失败）
• 因无法在合理时间内解析最终 URL 而超时（返回 408 - 超时）
• 出现某种异常  

如果出现异常，我们会使用以下原因与返回状态码之间的映射：

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

​

匹配规则

“匹配规则”扩展信息是一个元数据对象，用于指示接收到的 Posts 是由哪些规则匹配到的。这通常与 PowerTrack 流一起使用。

匹配通过对规则中包含的词项进行精确匹配来完成，会在有标点和去除标点的活动内容中进行扫描。匹配不区分大小写。当发现内容包含规则中定义的所有词项时，根级会出现一个 matching_rules 对象，指明导致匹配的规则。

PowerTrack

通过 PowerTrack（实时、回放和历史）传递的 Posts 将包含如下的 matching_rules 对象：

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

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

​

投票元数据

投票元数据是一种免费增强信息，适用于所有产品（实时与历史 API），以增强的原生格式负载提供。该元数据记录 Post 中是否包含投票，列出投票选项，并给出投票持续时间和到期时间。此增强信息便于识别投票的存在，并支持对用于展示的投票 Post 进行正确渲染。

重要说明：

• 适用于所有企业版 API（PowerTrack、Replay、Search、Historical PowerTrack）
  • 注意： 对于 Replay 和 Historical PowerTrack，此元数据自 2017/02/22 起首次提供。
• 不包含投票信息或投票结果
• 目前不支持筛选器/运算符
• 仅提供 增强的原生格式
  • 增强的原生格式是用户可控的设置，可随时通过 Console 更改：选择产品（PowerTrack、Replay、Search）> Settings 选项卡 > Output Format（保留 data 的原始格式）

​

Post 负载

投票类 Post 的负载中，在 “entities.polls” 对象内包含以下元数据：

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

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

​

示例载荷

下面是一个经过丰富的原生格式载荷片段，重点展示了新增的投票元数据：

"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 用户的个人资料包含用户提供的公开位置信息。该 data 作为普通字符串返回在 user.location 中（参见 User object data dictionary）。Profile Geo Enrichment 会在可能的情况下通过地理编码并规范化位置字符串，为 user.location 的取值添加结构化地理数据。仅当在企业版 API 产品中作为 Post 负载的一部分包含时，纬度/经度坐标及相关地点元数据才会添加到 user.derived.locations 中。使用 the enriched native format 时可获取这些 data，并可结合 PowerTrack rules 进行过滤。

注： 用于创建 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	一个数组，其中包含与创建该 Post 的用户所属的最低粒度地点相对应的坐标的经纬度值。

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

​

示例有效载荷

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "美国",
                    "country_code": "US",
                    "locality": "伯明翰",
                    "region": "阿拉巴马州",
                    "sub_region": "杰斐逊县",
                    "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 提供了一种不同于负载中原生 geo 值的替代地理类型。这两种地理类型可以结合使用，以覆盖与特定区域相关的所有可能 Post（基于可用地理数据），但二者在概念上并不等同。