データエンリッチメント：エンタープライズ

はじめに

Enterprise Enterprise のエンリッチメントは、一部の data API のレスポンスペイロードに含まれる追加のメタデータです。これらは有料サブスクリプションプランでのみ利用できます。以下の表では、各エンリッチメントの概要を説明します。

エンリッチメント:	説明:
URL の展開と拡充	Post の本文に含まれる短縮 URL（例: bitly）を自動展開し、遷移先ページの HTML タイトルと説明のメタデータを提供します。
マッチングルールオブジェクト	受信した Post にどのルールがマッチしたかを示します。レスポンスオブジェクトでルールタグとルール ID を返します。
投票メタデータ	Post 内に投票が含まれることを示し、投票の選択肢一覧に加え、投票の期間と終了時刻を含みます。
プロフィールの位置情報	可能な場合は［経度、緯度］座標を含む、ユーザープロフィールから導出された位置情報データと関連する場所メタデータです。

展開および拡張されたURL

Expanded and Enhanced URLのエンリッチメントは、Post本文に含まれる短縮URLを自動で展開し、得られたURLをペイロード内のメタデータとして含めます。さらに、このエンリッチメントは遷移先ページのtitleおよびdescriptionからHTMLページのメタデータも提供します。 重要な詳細:

短縮リンクを解決するために、当社のシステムは提供されたURLに対してHTTP HEADリクエストを送信し、最終的なURLに到達するまでリダイレクトに追従します。この最終URL（ページのコンテンツ自体ではありません）がレスポンスのペイロードに含まれます。
URLエンリッチメントはリアルタイムストリームに5〜10秒のレイテンシーを追加します
Full Archive Search APIへのリクエストでは、展開URLのエンリッチメントデータは13カ月以内のPostに対してのみ利用可能です。
URLエンリッチメントは、Post内に含まれるPostリンク（引用Tweetを含む）、Momentsリンク、プロフィールリンクには提供されません。

Post ペイロード

Expanded および Enhanced URL のエンリッチメントは、Post ペイロードの entities オブジェクト内、具体的には entitites.urls.unwound オブジェクトに含まれます。ここでは次のメタデータ fields が提供されます:

展開済み 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 メタデータの関連フィールドに対してフィルタリングを行い、トークン化された一致を返します。 url:

例: “url:tennis”
単語 tennis を含むあらゆる Expanded URL に対するトークン化一致
また、“url:npr.org” のように指定して、特定のウェブサイトのリンクを含める／除外するフィルターとしても使用できます

url_title:

例: “url_title:tennis”
単語 tennis を含むあらゆる Expanded URL の HTML タイトルに対するトークン化一致
レスポンスのペイロードに含まれる HTML タイトルに対してマッチします（最大 300 文字）。

url_description:

例: “url_description:tennis”
単語 tennis を含むあらゆる Expanded URL の HTML 説明に対するトークン化一致
レスポンスのペイロードに含まれる HTML 説明に対してマッチします（最大 1000 文字）。

HTTP ステータスコード

展開済み URL のエンリッチメントでは、展開対象の最終 URL の HTTP ステータスコードも提供します。通常は 200 になります。その他の 400 番台は、URL の解決に問題があることを示します。 URL の展開を試みる際には、さまざまなステータスコードが返される可能性があります。URL 展開の過程でリダイレクトが発生した場合は、次のいずれかに至るまで無期限に追従します。

200 番台のコードに到達（成功）
リダイレクト以外の系列コードに到達（失敗）
最終 URL を妥当な時間内に解決できずタイムアウト（408 - Timeout を返す）
何らかの例外が発生

例外が発生した場合は、以下の理由と返されるステータスコードの対応関係を使用します。

理由	返されるステータスコード
SSL 例外	403 (Forbidden)
URL により展開が許可されていない	405
ソケットタイムアウト	408 (Timeout)
Unknown Host 例外	404 (Not Found)
サポートされていない操作	404 (Not Found)
Connect 例外	404 (Not Found)
不正な引数	400 (Bad Request)
その他すべて	400 (Bad Request)

照合ルール

matching_rules のエンリッチメントは、受信した Post にどのルールが一致したかを示すメタデータオブジェクトです。これは主に PowerTrack ストリームで使用されます。照合は、ルールに含まれる語句に対する完全一致で行われ、アクティビティのコンテンツを句読点の有無の両方で走査します。大文字・小文字は区別しません。コンテンツ内にそのルールで定義されたすべての語句が含まれていると判定された場合、一致に至ったルールを示す、ルートレベルの matching_rules オブジェクトが含まれます。 PowerTrack PowerTrack（リアルタイム、Replay、Historical）で配信される Post には、以下のように matching_rules オブジェクトが含まれます。

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

PowerTrack では、matching_rules オブジェクトには、該当する結果に一致したルールがすべて反映されます。言い換えると、複数のルールが特定の Post に一致した場合でも配信は一度だけですが、matching_rules 要素には一致したすべてのルールが含まれます。

投票メタデータ

投票メタデータは、強化されたネイティブ形式のペイロードで提供される、すべての製品（Realtime および Historical API）共通の無料エンリッチメントです。このメタデータには、Post に投票が含まれていることのフラグ、投票の選択肢一覧、投票の実施期間と有効期限が含まれます。このエンリッチメントにより、投票の有無を容易に判別でき、表示用に投票付きの Post を適切にレンダリングできます。

重要な詳細:

すべてのエンタープライズ API（PowerTrack、Replay、Search、Historical PowerTrack）で利用可能
- 注: Replay と Historical PowerTrack では、このメタデータは 2017/02/22 に初めて提供されました。
投票情報および投票結果は含まれません
現在、フィルター／オペレーターはサポートされていません
拡張ネイティブ形式でのみ提供
- 拡張ネイティブ形式はユーザーが管理できる設定で、Console からいつでも変更できます: Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

Post ペイロード

投票付きの Post では、ペイロード内の「entities.polls」オブジェクトに次のメタデータが含まれます：

最大4つの選択肢を持つ「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 のユーザープロフィールには、ユーザーが提供した公開の位置情報が含まれています。このデータは user.location に通常の文字列として返されます（User object data dictionaryを参照）。Profile Geo Enrichment は、可能な場合に位置文字列をジオコーディングし正規化することで、user.location の値に関連する構造化ジオデータを追加します。緯度・経度の座標と関連する場所メタデータは、エンタープライズ API 製品において Post のペイロードの一部として含まれている場合にのみ、user.derived.locations に追加されます。このデータは拡張ネイティブ形式を使用する際に利用でき、PowerTrack ルールの組み合わせでフィルタリングできます。

注: Profile Geo エンリッチメントの作成に使用される補助的な地理データの一部は GeoNames.org に由来し、Creative Commons Attribution 3.0 License の下で X によって使用されています。

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 を作成したユーザーの出身国に対応する2文字の 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": "United States",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Jefferson County",
                    "full_name": "Birmingham, Alabama, United States",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

制限事項

Profile Geo エンリッチメントは、プロフィールの location 文字列に記載された地理的な場所について、最適な候補を推定します。類似名称の複数の場所が存在する、名称が曖昧である、などの要因により、結果が常に正確とは限りません。
ユーザーのプロフィールの location フィールド（actor.location）に値がない場合、分類は実施しません。
精度レベル: Profile Geo エンリッチメントが国または地域レベルでしか確度高く判定できない場合、subRegion や locality などの下位レベルの地理情報はペイロードから省略されます。
Profile Geo エンリッチメントは、エンリッチメント結果の精度レベルに対応する緯度・経度（単一点）を提供します。これらの座標は、エンリッチメントの位置結果の地理的中心を表します。たとえば、精度レベルが Country レベルであれば、その座標は当該 Country の地理的中心に設定されます。
アドレスプロパティ（locality/region/country/country code）向けに提供される PowerTrack 演算子は、多様なルールの組み合わせを可能にするために、意図的に細かく分かれています。同名の別の場所と名称を共有する特定の場所を狙う場合は、アドレスルールを組み合わせることを検討してください。たとえば、次のようにすると「San Francisco, Philippines」との一致を回避できます: profile_locality:“San Francisco” profile_region:California 個々の Profile Geo フィールドを対象とするルールを作成する際には、粒度を上げるほど取得できる結果が限定される点に留意してください。都市のデータを参照したい場合、地域が都市と大きく重なっているときには、region ルールのみに依拠するのが適切なケースもあります。例: スイスのチューリッヒは、profile_region:“Zurich” を用いることで周辺地域も含め効果的にターゲティングできます。
ネイティブ Geo の Post との併用: Profile Geo エンリッチメントは、ペイロード内のネイティブ geo 値とは異なる、Post に対する代替的な地理情報を提供します。これら2種類の地理情報は（利用可能な地理データに基づき）特定のエリアに関連する可能な限り多くの投稿を捕捉するために併用できますが、概念的に同等ではありません。

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

データエンリッチメント：エンタープライズ

はじめに

展開および拡張されたURL

Post ペイロード

フィルタリング演算子

HTTP ステータスコード

照合ルール

投票メタデータ

重要な詳細:

Post ペイロード

サンプルペイロード

プロフィールの位置情報

はじめに

プロフィールの地理データ

サンプルペイロード

制限事項

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

​はじめに

​展開および拡張されたURL

​Post ペイロード

​フィルタリング演算子

​HTTP ステータスコード

​照合ルール

​投票メタデータ

重要な詳細:

​Post ペイロード

​サンプルペイロード

​プロフィールの位置情報

​はじめに

​プロフィールの地理データ

​サンプルペイロード

​制限事項

はじめに

展開および拡張されたURL

Post ペイロード

フィルタリング演算子

HTTP ステータスコード

照合ルール

投票メタデータ

Post ペイロード

サンプルペイロード

プロフィールの位置情報

はじめに

プロフィールの地理データ

サンプルペイロード

制限事項