データエンリッチメント：Enterprise

はじめに

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

エンリッチメント:	説明:
Expanded and Enhanced URLs	Post の本文に含まれる短縮 URL（例: bitly）を自動展開し、遷移先ページの HTML の title と description のメタデータを取得して提供します。
Matching rules object	受信した Posts に一致したルールを示します。レスポンスのオブジェクト内でルールタグとルールの id を返します。
Poll metadata	Post にポールが含まれていることを示し、選択肢一覧に加えて、ポールの実施期間と終了時刻を含みます。
Profile geo	可能な場合、［経度、緯度］座標を含む、ユーザープロフィールの位置情報（派生値）と関連する場所のメタデータです。

拡張および強化されたURL

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

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

Post ペイロード

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

Expanded URL - unwound.url
Expanded HTTP ステータス - unwound.status
Expanded URL の HTML タイトル（最大 300 文字）- unwound.title
Expanded 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”
単語 tennis を含む任意の Expanded URL の HTML タイトルに対してトークン化された一致
ペイロードに含まれる HTML タイトルの data に対して一致し、最大 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)
接続例外	404 (Not Found)
不正な引数	400 (Bad Request)
その他すべて	400 (Bad Request)

マッチングルール

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

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

PowerTrack では、matching_rules オブジェクトは該当する結果にマッチしたルールをすべて反映します。つまり、特定の Post に複数のルールがマッチした場合でも、配信は一度だけ行われますが、matching_rules 要素にはマッチしたすべてのルールが含まれます。

投票のメタデータ

投票のメタデータは、強化済みネイティブ形式のペイロード内で、すべてのプロダクト（Realtime および Historical APIs）にわたり無償で利用できるエンリッチメントです。メタデータには、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 ペイロード

Poll の Post には、ペイロード内の「entities.polls」オブジェクトに以下の metadata が含まれます:

位置 (1～4) とオプションのテキストを含む、最大 4 件の選択肢を持つ「options」配列
Poll の終了日時
Poll の実行期間

参考として、以下のサンプルペイロードを参照してください。

サンプルペイロード

以下は、拡張されたネイティブ形式のペイロードのうち、追加された投票の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 のユーザープロフィールには、ユーザーが提供した公開の位置情報が含まれています。この data は user.location に通常の文字列として返されます（ユーザーオブジェクト data 辞書を参照）。Profile Geo Enrichment は、可能な場合に位置文字列をジオコーディングおよび正規化して、user.location の値に関連する構造化された地理データを追加します。緯度・経度の座標および関連する場所の metadata は、Enterprise API 製品で Post ペイロードに含まれている場合にのみ、user.derived.locations に追加されます。この data は拡張ネイティブ形式で利用でき、PowerTrack ルールを組み合わせてフィルタリングできます。

注: Profile Geo Enrichment の作成に使用される補助的な地理データの一部は GeoNames.org に由来し、X はそれをCreative Commons Attribution 3.0 Licenseの下で使用しています。

Profile Geo の data は、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	下記参照	Post を作成したユーザーの居住地の最も細かい粒度の位置に対応する座標の緯度/経度を含む配列。

Historical PowerTrack、Search、PowerTrack API は、プロフィールの地理データに基づくフィルタリングをサポートします。プロフィールの地理データで利用可能なフィルタリング用オペレーターの詳細は、該当する製品ドキュメントをご参照ください。

サンプルペイロード

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "アメリカ合衆国",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "アラバマ州",
                    "sub_region": "ジェファーソン郡",
                    "full_name": "バーミンガム、アラバマ州、アメリカ合衆国",
                    "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 の Posts と併用する場合: Profile Geo エンリッチメントは、ペイロード内のネイティブな geo 値とは異なる、Post に対する代替的な地理情報を提供します。これら2種類の地理情報は、（利用可能な地理データに基づき）特定のエリアに関連する可能性のあるすべての Posts を捕捉するために組み合わせて利用できますが、概念的に同等ではありません。

概要

Posts

ユーザー

ダイレクトメッセージ

いいね

List

Spaces

コミュニティ

コミュニティノート

トレンド

メディア

使用方法

stream 接続

コンプライアンス

Enterprise v2

Likes Streams

GNIP 2.0

データエンリッチメント：Enterprise

はじめに

拡張および強化されたURL

Post ペイロード

フィルタリング演算子

HTTP ステータスコード

マッチングルール

投票のメタデータ

重要な詳細:

Post ペイロード

サンプルペイロード

プロフィールの位置情報

はじめに

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

サンプルペイロード

制限事項

概要

Posts

ユーザー

ダイレクトメッセージ

いいね

List

Spaces

コミュニティ

コミュニティノート

トレンド

メディア

使用方法

stream 接続

コンプライアンス

Enterprise v2

Likes Streams

GNIP 2.0

​はじめに

​拡張および強化されたURL

​Post ペイロード

​フィルタリング演算子

​HTTP ステータスコード

​マッチングルール

​投票のメタデータ

重要な詳細:

​Post ペイロード

​サンプルペイロード

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

​はじめに

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

​サンプルペイロード

​制限事項

はじめに

拡張および強化されたURL

Post ペイロード

フィルタリング演算子

HTTP ステータスコード

マッチングルール

投票のメタデータ

Post ペイロード

サンプルペイロード

プロフィールの位置情報

はじめに

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

サンプルペイロード

制限事項