ご留意ください。 X API v2 で 投稿の検索 と 投稿数 の新しいバージョンをリリースしました。X API v2 の新機能をご確認ください。 これらのエンドポイントは、ポストの編集メタデータを含むように更新されています。これらのメタデータの詳細については、“Edit Posts” の基礎ページ を参照してください。
Overview
Enterprise
エンタープライズ API は、当社の管理されたアクセスレベルでのみ利用可能です。これらの API を使用するには、まずエンタープライズ営業チームを通じてアカウントを開設する必要があります。詳細については こちら をご覧ください。
X API におけるすべての検索系ポストオファリングは こちら から確認できます。
エンタープライズ検索 API には次の 2 種類があります。
- 30-Day Search API は、直近 30 日間のデータを提供します。
- Full-Archive Search API は、2006 年 3 月の最初のポストまでさかのぼる、X データ全体のコーパスへの完全かつ即時のアクセスを提供します。
リクエストの種類
Search requests (data)
maxResults パラメータを使用すると、表示用途向けに小さいページサイズを指定して (必要に応じてユーザーがさらに結果を要求できるようにする) 、または大規模なデータ取得向けに大きいページサイズ (最大 500) を指定することができます。データは新しいものから順に (逆時系列で) 配信され、配信時点でコンプライアンス要件に準拠しています。
Counts requests (投稿数)
使用可能なオペレーター
| ポスト内容に対するマッチング: | 関心のあるアカウントに対するマッチング: | ポスト属性: | 地理空間オペレーター: |
| * keyword * “quoted phrase” * “keyword1 keyword2”~N * # * @ * $ * url: * lang: | * from: * to: * retweets_of: | * is:retweet * has:mentions * has:hashtags * has:media * has:videos * has:images * has:links * has:symbols * is:verified * -is:nullcast (否定専用オペレーター) | * bounding_box:[west_long south_lat east_long north_lat] * point_radius:[lon lat radius] * has:geo * place: * place_country: * has:profile_geo * profile_country: * profile_region: * profile_locality: |
"#cats" は Search API で cats として解釈されます。lang: オペレーターおよびすべての is: と has: オペレーターは単独では使用できず、必ず別の句と組み合わせてください (例: @XDevelopers has:links)。
Search API では、トークナイズ／マッチング機能の制約により、使用できるオペレーターは限定されています。Enterprise リアルタイムおよびバッチ履歴 API では、追加のオペレーターが利用できます。詳細はこちらを参照してください。
さらに詳しくは、オペレーター入門ガイドを参照してください。
データの利用可能性 / 重要な日付
- 最初のポスト: 3/21/2006
- 最初のネイティブリツイート: 11/6/2009
- 最初の位置情報付きポスト: 11/19/2009
- フィルタリング用に URL が初めてインデックス化: 8/27/2011
- URL 展開メタデータの拡張 (Web サイトのタイトルと説明文) : 12/1/2014
- プロフィール位置情報のエンリッチメントメタデータおよびフィルタリング: 2/17/2015
データの更新と可変性
- User オブジェクトのメタデータ:
- ユーザーの @handle (数値の ID は決して変わりません)
- 自己紹介 (Bio) テキスト
- 各種カウント: statuses、followers、friends、favorites、lists
- プロフィールの位置情報
- タイムゾーンや言語などのその他の詳細
- ポストの統計値 - つまり、ユーザーの操作によってプラットフォーム上で変更されうるもの (以下は例) :
- Favorites 数
- Retweet 数
シングルスレッド vs. マルチスレッドリクエスト
リトライロジック
- 対象としている時間範囲を短くしてリクエストを再試行します。うまくいかない場合は、最短で 6 時間の時間範囲になるまで繰り返します。
- 多数の検索語を OR 条件でまとめている場合は、それらを複数のルールに分割し、それぞれを個別に再試行します。
- ルール内で多数の除外条件を使用している場合は、ルール内の否定条件の語句の数を減らして再試行します。
クイックスタート
enterprise Search Posts: 30-Day API を使い始める
- [An enterprise account]https://developer.x.com/en/products/x-api/enterprise
- ユーザー名、パスワード、アカウント名
- console.gnip.com に表示される、検索エンドポイントに紐づいたラベル
データエンドポイントへのアクセス
from: および lang: 演算子を使用して、@XDevelopers による英語の投稿を検索します。 他の演算子については こちらを参照してください。
- cURL
- cURL の例
cURL は、URL 構文を使用してファイルを取得または送信するためのコマンドラインツールです。以下の cURL リクエストを、次の項目を変更したうえでコマンドラインにコピーしてください。
-
Username
<USERNAME>(例)email@domain.com -
Account name
<ACCOUNT-NAME>(例)john-doe -
Label
<LABEL>(例)prod -
fromDate と toDate (例)
"fromDate":"201811010000", "toDate":"201811122359"
データエンドポイントのレスポンスペイロード
API リクエストに対するレスポンスのペイロードは、以下の例のように JSON 形式になります。counts エンドポイントへのアクセス
day ごとにグループ化して取得します。
- cURL
- cURL example
cURL は、URL 構文を使用してファイルを取得または送信するためのコマンドラインツールです。次の cURL リクエストをコマンドラインにコピーし、以下の項目を変更してください。
-
Username
<USERNAME>例:email@domain.com -
Account name
<ACCOUNT-NAME>例:john-doe -
Label
<LABEL>例:prod -
fromDate と toDate 例:
"fromDate":"201811010000", "toDate":"201811122359"
カウントエンドポイントのレスポンスペイロード
API リクエストに対するレスポンスのペイロードは、以下の例のように JSON 形式で返されます。関連記事
enterprise Search Posts: Full-Archive API を使い始める
data 形式、またはマッチした投稿の数値カウントデータを取得できる counts 形式のいずれかになります。ここでは、cURL を使用して data エンドポイントと counts エンドポイントにリクエストを送信します。
次のものが必要です。
- [エンタープライズアカウント]https://developer.x.com/en/products/x-api/enterprise
- ユーザー名、パスワード、アカウント名
- console.gnip.com に表示される、検索エンドポイントに関連付けられているラベル
データエンドポイントへのアクセス
from: と lang: オペレーターを使用して、@XDevelopers から英語で投稿された投稿を検索します。 他のオペレーターについては こちらを参照してください。
- cURL
- cURL example
cURL は、URL 構文を使用してファイルを取得または送信するためのコマンドラインツールです。次の cURL リクエストを、以下の項目を変更したうえでコマンドラインにコピーしてください。
-
Username
<USERNAME>例:email@domain.com -
Account name
<ACCOUNT-NAME>例:john-doe -
Label
<LABEL>例:prod -
fromDate と toDate 例:
"fromDate":"201802010000", "toDate":"201802282359"
データエンドポイントのレスポンスペイロード
カウント用エンドポイントへのアクセス
カウント用エンドポイントを使って、英語の @XDevelopers アカウント発の投稿数を、day ごとに集計して取得します。
- cURL
- cURL example
cURL は、URL 構文を使用してファイルを取得または送信するためのコマンドラインツールです。以下の項目を自身の値に置き換えたうえで、次の cURL リクエストをコマンドラインにコピーしてください。
-
Username
<USERNAME>例:email@domain.com -
Account name
<ACCOUNT-NAME>例:john-doe -
Label
<LABEL>例:prod -
fromDate と toDate 例:
"fromDate":"201802010000", "toDate":"201802282359"
Counts エンドポイントのレスポンスペイロード
参考資料
ガイド
検索クエリの作成
エンタープライズ向けオペレーター
- Enterprise 30 日検索 API
- Enterprise フルアーカイブ検索 API
| 演算子 | 説明 |
|---|---|
| キーワード | ポストの本文または URL 内のトークン化されたキーワードにマッチします。これはトークン化に基づく照合であり、指定したキーワード文字列はポスト本文のトークン化されたテキストと比較されます。トークン化は、句読点、記号、および区切り文字に該当する Unicode 基本多言語面の文字に基づいて行われます。たとえば、テキストが “I like coca-cola” のポストは、次のトークンに分割されます: I, like, coca, cola。これらのトークンが、ルールで使用したキーワード文字列と比較されます。句読点 (例: coca-cola) 、記号、または区切り文字を含む文字列にマッチさせるには、以下で説明する引用符付きの完全一致を使用する必要があります。 注: Search API では、アクセント付き文字や特殊文字は標準的なラテン文字に正規化されます。これにより、外国語における意味が変化したり、予期しない結果が返されたりする可能性があります。 たとえば、“músic” は “music” にマッチし、その逆も同様です。 また、スペイン語の一般的なフレーズ “Feliz Año Nuevo!” は、インデックス時に “Feliz Ano Nuevo” として扱われ、フレーズの意味が変化します。 注: このオペレーターは、ポスト内の URL と展開済み URL の両方にマッチします。 |
| 絵文字 | ポスト本文中の絵文字にマッチします。絵文字はトークン単位でマッチし、指定した絵文字はポスト本文のトークン化されたテキストと照合されます。トークン化は句読点、記号／絵文字、および区切り用の Unicode 基本多言語面文字に基づきます。たとえば、「I like 」というテキストを含むポストは、次のトークンに分割されます: I, like, 。これらのトークンが、ルールで使用する絵文字と比較されます。絵文字にバリアントがある場合は、その絵文字をルールに追加する際に必ず引用符 (” ”) で囲んでください。 |
| “完全一致フレーズ” | ポストの本文または URL 内の、トークン化され順序付けられたフレーズに一致します。これはトークン単位での一致であり、指定したキーワード文字列が、ポスト本文をトークン化したテキストと照合されることを意味します。トークン化は句読点、記号、および区切り記号にあたる Unicode 基本多言語面の文字に基づいて行われます。 注: 句読点はトークン化されず、空白として扱われます。 たとえば、引用符付きの “#hashtag” は “hashtag” には一致しますが、#hashtag には一致しません (実際のハッシュタグに一致させるには、引用符なしの hashtag # 演算子を使用してください) 。 たとえば、引用符付きの “cashtag には一致しません (実際のキャッシュタグに一致させるには、引用符なしの cashtag $ 演算子を使用してください) 。 たとえば、“Love Snow” は “#love #snow” に一致します。 たとえば、“#Love #Snow” は “love snow” に一致します。 注: この演算子は、ポスト内の URL と展開された (unwound) URL の両方に一致します。 |
| “keyword1 keyword2”~N | 一般的に近接演算子と呼ばれ、この演算子はキーワード同士が互いに N 個以内のトークンしか離れていないポストにマッチします。 キーワードの順序が逆の場合、互いに N-2 個より多くトークンが離れていてはなりません。引用符内には任意の数のキーワードを含めることができます。N は 6 を超えることはできません。 この演算子は enterprise 検索 API でのみ利用可能である点に注意してください。 |
| from: | 特定のユーザーからのあらゆるポストにマッチします。 値には、そのユーザーの X の数値アカウント ID かユーザー名 (@ 文字を除く) を指定する必要があります。数値の X アカウント ID を取得する方法については、こちら または こちら を参照してください。 |
| to: | 特定のユーザーへの返信である任意のポストに一致します。 値には、そのユーザーの数値XアカウントIDまたはユーザー名 (@ 文字を除く) を指定する必要があります。数値XアカウントIDの検索方法については、こちら を参照してください。 |
| url: | ポスト内に含まれる展開済み URL に対してトークン化 (キーワード／フレーズ) マッチを実行します (url_contains と同様) 。句読点や特殊文字を含むトークンやフレーズは二重引用符で囲む必要があります。たとえば、url:“/developer” のように指定します。一般には推奨しませんが、特定のプロトコルに対してマッチさせたい場合は、二重引用符で囲んで指定します：url:“https://developer.x.com"。注: PowerTrack または Historical PowerTrack を使用する場合、このオペレーターは引用ポストの元となるオリジナルのポスト内に含まれる URL に対してマッチします。たとえば、ルールに url:“developer.x.com” を含めており、あるポストがその URL を含んでいる場合、そのポストを引用したすべてのツイートも結果に含まれます。これは Search API を使用する場合には当てはまりません。 |
| # | 指定されたハッシュタグを含む任意の投稿にマッチします。 このオペレーターはトークン化されたマッチではなく、完全一致でマッチを行います。つまり、ルール「2016」は、ハッシュタグ「2016」を持つ投稿にはマッチしますが、ハッシュタグ「2016election」を持つ投稿にはマッチしません。 注意: ハッシュタグオペレーターは、本文からハッシュタグを抽出するのではなく、X のエンティティ抽出に依存してハッシュタグをマッチさせます。X Entities の JSON 属性の詳細については こちら を参照してください。 |
| @ | 指定したユーザー名に言及しているポストすべてにマッチします。 to: 演算子は、@mention 演算子でマッチするポストの部分集合を返します。 |
| $ | 指定された「キャッシュタグ」 (トークンの先頭文字が「$」であるもの) を含む任意のポストにマッチします。 このキャッシュタグ演算子は、本文からキャッシュタグを直接抽出しようとするのではなく、X の「symbols」エンティティ抽出機能に依存してキャッシュタグをマッチングする点に注意してください。X Entities の JSON 属性の詳細は、こちらを参照してください。 なお、この演算子は enterprise 検索 API でのみ利用可能です。 |
| retweets_of: | 利用可能なエイリアス: retweets_of_user: 指定したユーザーのリツイート投稿に一致します。ユーザー名と数値の X アカウント ID の両方を受け付けます (ポストのステータス ID ではありません) 。数値の X アカウント ID を検索する方法については、こちらを参照してください。 |
| lang: | X によって特定の言語として分類された投稿にマッチします (ポストが分類されている場合に限ります) 。各ポストは現在 1 つの言語にのみ分類されるため、複数の言語を AND 条件で指定しても結果は返されない点に注意してください。 注: 言語の分類が行えない場合、返される値は「und」 (undefined) になります。 以下の一覧は、現在サポートされている言語と、それぞれに対応する BCP 47 言語識別子を表しています。 |
| アムハラ語: am | ドイツ語: de | マラヤーラム語: ml | スロバキア語: sk |
| アラビア語: ar | ギリシャ語: el | ディベヒ語 (モルディブ語) : dv | スロベニア語: sl |
| アルメニア語: hy | グジャラート語: gu | マラーティー語: mr | ソラニ・クルド語: ckb |
| バスク語: eu | ハイチ・クレオル語: ht | ネパール語: ne | スペイン語: es |
| ベンガル語: bn | ヘブライ語: iw | ノルウェー語: no | スウェーデン語: sv |
| ボスニア語: bs | ヒンディー語: hi | オリヤー語: or | タガログ語: tl |
| ブルガリア語: bg | ローマ字表記のヒンディー語: hi-Latn | パンジャーブ語: pa | タミル語: ta |
| ビルマ語 (ミャンマー語) : my | ハンガリー語: hu | パシュトー語: ps | テルグ語: te |
| クロアチア語: hr | アイスランド語: is | ペルシャ語: fa | タイ語: th |
| カタロニア語: ca | インドネシア語: in | ポーランド語: pl | チベット語: bo |
| チェコ語: cs | イタリア語: it | ポルトガル語: pt | 繁体字中国語: zh-TW |
| デンマーク語: da | 日本語: ja | ルーマニア語: ro | トルコ語: tr |
| オランダ語: nl | カンナダ語: kn | ロシア語: ru | ウクライナ語: uk |
| 英語: en | クメール語: km | セルビア語: sr | ウルドゥー語: ur |
| エストニア語: et | 韓国語: ko | 簡体字中国語: zh-CN | ウイグル語: ug |
| フィンランド語: fi | ラオ語: lo | シンド語: sd | ベトナム語: vi |
| フランス語: fr | ラトビア語: lv | シンハラ語: si | ウェールズ語: cy |
| ジョージア語: ka | リトアニア語: lt |
| place: | 指定された場所 または X place ID (例を参照) でタグ付けされた投稿にマッチします。複数語から成る地名 (“New York City” や “Palo Alto” など) は引用符で囲む必要があります。 注: X place ID の取得方法については、公開 API エンドポイント GET geo/search を参照してください。 注: Retweet の場所情報は元のポストに紐付いているため、このオペレーターは Retweet にはマッチしません。また、Quote Tweet の元のポストに紐付いている場所にもマッチしません。 |
| place_country: | タグ付けされた place に関連付けられている国コードが、指定された ISO アルファベット 2 文字コードと一致する投稿にマッチします。 有効な ISO コードは以下を参照してください: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 注: Retweet の場所情報は元のポストに紐付いているため、このオペレーターは Retweet にはマッチしません。また、Quote Tweet の元のポストに紐付いている場所にもマッチしません。 |
| point_radius:[lon lat radius] | 存在する場合はポストの厳密な位置 (x, y) 、および X では「Place」のジオポリゴンに対して評価され、Place が定義された領域内に完全に含まれている場合にマッチします。 * サポートされる半径の単位はマイル (mi) とキロメートル (km) です。 * 半径は 25mi 未満である必要があります。 * 経度は ±180 の範囲です。 * 緯度は ±90 の範囲です。 * すべての座標は 10 進法の度数 (decimal degrees) で指定します。 * ルール引数は角括弧で囲み、スペース区切りで指定します。 注: Retweet の場所情報は元のポストに紐付いているため、このオペレーターは Retweet にはマッチしません。また、Quote Tweet の元のポストに紐付いている場所にもマッチしません。 |
| bounding_box:[west_long south_lat east_long north_lat] | 利用可能なエイリアス: geo_bounding_box: 存在する場合はポストの厳密な位置 (long, lat) 、および X では「Place」のジオポリゴンに対して評価され、Place が定義された領域内に完全に含まれている場合にマッチします。 * west_long と south_lat はバウンディングボックスの南西端を表し、west_long がその地点の経度、south_lat がその地点の緯度です。 * east_long と north_lat はバウンディングボックスの北東端を表し、east_long がその地点の経度、north_lat がその地点の緯度です。 * バウンディングボックスの幅と高さは 25mi 未満である必要があります。 * 経度は ±180 の範囲です。 * 緯度は ±90 の範囲です。 * すべての座標は 10 進法の度数 (decimal degrees) で指定します。 * ルール引数は角括弧で囲み、スペース区切りで指定します。 注: Retweet の場所情報は元のポストに紐付いているため、このオペレーターは Retweet にはマッチしません。また、Quote Tweet の元のポストに紐付いている場所にもマッチしません。 |
| profile_country: | Profile Geo エンリッチメントの「address」オブジェクト内の「countryCode」フィールドに対する完全一致です。 ISO-3166-1-alpha-2 仕様に基づく正規化された 2 文字の国コードセットを使用します。このオペレーターは、簡潔にするために「address」オブジェクト内の「country」フィールド用オペレーターの代替として提供されています。 |
| profile_region: | Profile Geo エンリッチメントの「address」オブジェクト内の「region」フィールドにマッチします。 これは文字列全体に対する完全一致です。バックスラッシュで文字をエスケープする必要はありません。たとえば、スラッシュを含むものにマッチさせる場合は「one/two」を使用し、「one/two」は使用しません。空白や句読点を含む部分文字列にマッチさせるには、二重引用符を使用してください。 |
| profile_locality: | Profile Geo エンリッチメントの「address」オブジェクト内の「locality」フィールドにマッチします。 これは文字列全体に対する完全一致です。バックスラッシュで文字をエスケープする必要はありません。たとえば、スラッシュを含むものにマッチさせる場合は「one/two」を使用し、「one/two」は使用しません。空白や句読点を含む部分文字列にマッチさせるには、二重引用符を使用してください。 |
注:
is: および has: オペレーターは、Search API を使用する場合に単独では使用できず、必ず別の句と組み合わせて使用する必要があります。たとえば、@XDeevelopers has:links| has:geo | X によって提供された、ポスト固有の位置情報データを持つ投稿にマッチします。これは、「geo」による緯度・経度座標、または対応する表示名、ジオポリゴン、その他のフィールドを含む、X の “Place” 形式の「location」のいずれかです。 注記: Search API を使用する場合、このオペレーターは、 is: や has: を含まない他のオペレーターと併用する必要があります。 |
| has:profile_geo | 利用可能な別名: has:derived_user_geo 実際の値の内容に関わらず、任意の Profile Geo メタデータを持つ投稿にマッチします。 注: Search API を使用する場合、このオペレーターは、 is: や has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
| has:links | このオペレーターは、メッセージ本文にリンクを含む投稿にマッチします。 注: Search API を使用する場合、このオペレーターは、 is: または has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
| is:retweet | ルールに一致する明示的なリツイートのみを配信します。否定形で使用すると、ルールに一致するリツイートは配信対象から除外され、オリジナルのコンテンツのみが配信されます。 このオペレーターは、X のリツイート機能を使用した通常のリツイートのみを対象とします。X のリツイート機能を使用していない引用ツイートや内容を変更した投稿は、このオペレーターではマッチしません。 注: Search API を使用する場合、このオペレーターは、 is: や has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
| is:reply | 投稿が他の投稿への返信であるかどうかに基づいてフィルタリングするためのオペレーターです。ルールに一致する明示的な返信のみを配信します。ルールに一致する返信を配信対象から除外するように、このオペレーターを否定形で使用することもできます。 なお、このオペレーターは有料の Premium および Enterprise 検索で利用可能であり、Sandbox 開発環境では利用できません。 注: Search API を使用する場合、このオペレーターは、 is: や has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
| is:quote | 別のポストを参照する投稿、つまり Post ペイロード内の “is_quote_status”:true で識別される引用ツイートのみを配信します。否定形を指定することで、引用ツイートを除外することもできます。 注意: Search API を使用する場合、このオペレーターは、 is: や has: を含まない他のオペレーターと併用する必要があります。 |
| is:verified | X によって「認証済み」とされている投稿者の投稿のみを返します。また、否定形を使用すると、投稿者が認証済みである投稿を除外できます。 注: Search API を使用する場合、この演算子は、 is: や has: を含まない他の演算子と組み合わせて使用する必要があります。 |
| has:mentions | 他の X ユーザーに言及している投稿にマッチします。 注意: Search API を使用する場合、この演算子は、 is: または has: を含まない他の演算子と組み合わせて使用する必要があります。 |
| has:hashtags | ハッシュタグを含む投稿に一致します。 注: Search API を使用する際は、この演算子を、 is: または has: を含まない他の演算子と組み合わせて使用する必要があります。 |
| has:media | 利用可能な別名: has:media_link X によってメディアとして分類された URL を含む投稿にマッチします。例: pic.x.com。 注: Search API を使用する際は、このオペレーターを is: または has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
| has:images | X によってメディア URL として分類された URL を含む投稿にマッチします。例: pic.x.com。 注: Search API を使用する場合、この演算子は、 is: または has: を含まない他の演算子と組み合わせて使用する必要があります。 |
| has:videos | 使用可能なエイリアス: has:video_link ネイティブな X 動画 (X に直接アップロードされた動画) を含む投稿にマッチします。Vine や Periscope で作成された動画、または他の動画ホスティングサイトへのリンクを含む投稿にはマッチしません。 注意: Search API を使用する場合、この演算子は、 is: または has: を含まない他の演算子と組み合わせて使用する必要があります。 |
| has:symbols | 先頭に「tag) 。このオペレーターは enterprise 検索 API でのみ利用可能です。 注: Search API を使用する場合、このオペレーターは is: または has: を含まない他のオペレーターと組み合わせて使用する必要があります。 |
製品概要
メタデータのタイムライン
to: や in_reply_to_status_id: PowerTrack Operator に頼るのではなく、ポスト本文を調査する必要があります。
ここに記載されている詳細は、Full-Archive Search を用いて、数百件におよぶ検索を行った結果に基づいて生成されています。このタイムラインは 100% 完全でも精密でもありません。ユースケースにとって重要となる、他のフィルタリング／メタデータの「誕生日」を見つけた場合は、ぜひお知らせください。
なお、基盤となる Search インデックスは再構築される可能性があります。そのため、これらのタイムラインの詳細は変更される場合があります。
2006
- 3月26日 -
lang:。検索インデックスを生成する際に、ポストのメタデータがバックフィルされる例。 - 7月13日 -
has:mentionsのマッチングが開始。 - 10月6日 -
has:symbols。株式銘柄について議論するための slang) だったと考えられる。 - 10月26日 -
has:linksのマッチングが開始。 - 11月23日 -
has:hashtagsのマッチングが開始。
2007
- 1月30日 - @reply が初めて first-class 扱いとなり (in_reply_to_user_id) 、
reply_to_status_id:のマッチングが始まる。 - 8月23日 - トピックや会話を整理する一般的な慣習としてハッシュタグが登場。1週間後に最初の本格的な利用例が現れる。
2009
- 5月15日 -
is:retweet。このオペレーターは、公式リツイートの「ベータ」版リリースおよびその「Via @」パターンから一致するようになります。このベータ期間中は、ポストの動詞は「post」となり、元のポストはペイロードに含まれません。 - 8月13日 - 公式リツイートの最終版が、「RT @」パターン、動詞「share」、および元のポストを含む
retweet_status属性とともにリリースされます (そのため JSON ペイロードサイズはおおよそ2倍になります) 。
2010
- 3月6日 -
has:geo、bounding_box:およびpoint_radius:の地理演算子でのマッチングが開始される。 - 8月28日 -
has:videos(2015年2月まで、この演算子は、youtube.com や vimeo.com、vivo.com など一部の動画ホスティングサイトへのリンクを含む投稿にマッチします) 。
2011
- 7月20日 -
has:mediaとhas:imagesが検索でマッチするように。ネイティブ写真機能は2010年8月9日に正式発表。
2014
- 12月3日ごろ - 一部の Enhanced URL metadata が HTML の title と description とともにペイロードに含まれるようになりました。拡張メタデータは 2016年5月に、より完全な形で導入されました。
2015
- 2月10日 -
has:videosは「ネイティブ」な X 動画にマッチします。 - 2月17日 -
has:profile_geo,profile_country:,profile_region:,profile_locality:Profile Geo オペレーターがマッチングに対応し始めます。 - 2月17日 -
place_country:とplace:ポストのジオオペレーターがマッチングに対応し始めます。
2016
- 5月1日 - Enhanced URL metadata が本格的に利用可能となり、2016年8月の Gnip 2.0 ローンチ の一部として正式に発表されました。Search API には、これらのメタデータに対応する Operator は用意されていません。
2017
- 2月22日 - 投票メタデータが拡張されたネイティブ形式で利用可能になりました。これらのメタデータに対応する Operator はありません。
2022
- 9月27日 - この日以降に作成されたすべてのポストオブジェクトには、編集ポストのメタデータが利用可能です。ポストオブジェクトを提供するすべての Enterprise エンドポイントは、この日からこのメタデータを提供するように更新されました。提供される編集メタデータには、
edit_historyおよびedit_controlsオブジェクトが含まれます。これらのメタデータは、2022年9月27日以前に作成された投稿については返されません。現時点では、これらのメタデータに対応する Enterprise Operator はありません。編集ポストのメタデータについて詳しくは、Edit Posts fundamentals ページを参照してください。
2022
- 9月29日 - この日以降に作成されたすべてのポストオブジェクトでは、編集済みポストのメタデータが利用可能です。ポストオブジェクトを提供するすべての Enterprise エンドポイントは、この日からこのメタデータを提供するように更新されました。提供される編集メタデータには、edit_history オブジェクトと edit_controls オブジェクトが含まれます。これらのメタデータは、2022年9月27日より前に作成された投稿については返されません。現在のところ、これらのメタデータに対応する Enterprise Operators は存在しません。ポスト編集メタデータの詳細については、ポスト編集の基本 ページを参照してください。
フィルタリングのヒント
- 一部のメタデータには「付与開始日」があるため、フィルターの結果に 偽陰性 が含まれる可能性があります。これは、検索期間全体または一部では存在していなかったメタデータに依存するオペレーターを使った検索です。たとえば、
has:imagesオペレーターを使ってポストを検索する場合、2011 年 7 月より前の期間についてはヒットが一切ありません。これは、そのオペレーターが (X のユーザーインターフェースを使ってポストに添付された) ネイティブ 写真にマッチするためです。写真共有ポストのより完全なデータセットを取得するには、2011 年 7 月より前の期間に対するフィルターでは、写真ホスティング用の一般的な URL にマッチするルール句を含める必要があります。 - 一部のメタデータは、ポストが X に投稿された時点より 後 の時点のメタデータでバックフィルされています。
- X Profiles
- オリジナルポストまたは共有ポスト
- ポストの言語分類
- 位置情報参照付きポスト
- 共有リンクのメディア
X プロフィール
元の投稿とリツイート
_is:retweet_ オペレーターを使うと、リツイートを含めるか除外するかを指定できます。このオペレーターを利用する場合、2009 年 8 月以前のデータについては、リツイートとしてマッチさせるか (あるいはマッチさせないか) のために 2 つの戦略を用意しておく必要があります。2009 年 8 月以前は、「@RT 」パターンに一致するかどうかを確認するために、ポスト本文自体を正確なフレーズ一致でチェックする必要があります (実際には、2009 年 5〜8 月のリツイートをフィルタリングする場合は、「Via @」パターンも含める必要があります) 。2009 年 8 月以降の期間については、is:retweet オペレーターが利用可能です。
ポストの言語分類
lang: オペレーターはすべてのポストのアーカイブ全体に対して利用できます。
ポストの地理参照
- 投稿本文内の地理的な記述。 投稿本文内の地理的な記述に基づいてマッチングする方法は、ローカルな知識に依存するため最も難しい方法であることが多いものの、全投稿アーカイブに対して利用できるオプションです。こちらは、「golden gate」フィルターに基づいてサンフランシスコ地域を対象に 2006 年に行われた地理参照マッチの例です。
-
ユーザーがジオタグ付けした投稿。 Search APIs では、2010 年 3 月から一部の Geo オペレーターを使って投稿のマッチングができるようになり、2015 年 2 月からは他の Geo オペレーターも利用可能になりました。
- 2010 年 3 月 6 日:
has:geo、bounding_box:、point_radius: - 2015 年 2 月 17 日:
place_country:、place:
- 2010 年 3 月 6 日:
-
ユーザーがアカウントプロフィールの「ホーム」位置情報を設定。 Profile Geo オペレーターは Historical PowerTrack と Search APIs の両方で利用できます。Search APIs では、これらの Profile Geo メタデータは 2015 年 2 月から利用可能です。Profile Geo メタデータが利用可能になる前に投稿されたコンテンツについては、正規化されていないユーザー入力にマッチさせるために使用できる
bio_location:オペレーターが用意されています。
- 2006年10月26日 -
has:links - 2011年7月20日 -
has:imagesとhas:media - 2011年8月 -
url:(Expanded URLs エンリッチメント を利用) 。早い例では 2006 年 9 月の(url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube)が http://x.com/Adam/statuses/16602 にマッチします。twitter_entities や gnip オブジェクトには urls[] メタデータが存在しないにもかかわらずです。"youtube.com"は、urls[] メタデータが一切なくてもurl:youtubeにマッチするメッセージコンテンツの一例です。 - 2015年2月10日 - ネイティブ動画に対する
has:videos。2010/08/28 から 2015/02/10 の間、このオペレーターは youtube.com、vimeo.com、vivo.com などの特定の動画ホスティングサイトへのリンクを含むポストにマッチします。 - 2016年5月1日 - Enhanced URLs エンリッチメント に基づく
url_title:とurl_description:が一般提供開始。最初の強化 URL メタデータは 2014 年 12 月に現れ始めました。
よくある質問 (FAQ)
Search Post API 全般に関する質問
data エンドポイントで取得できる投稿数が、counts エンドポイントでカウントされる投稿数と一致しません。なぜですか？
data エンドポイントで取得できる投稿数が、counts エンドポイントでカウントされる投稿数と一致しません。なぜですか？
counts エンドポイントと data エンドポイントによって提供される結果には、差異が生じることが知られています。counts エンドポイントはコンプライアンス適用前 (削除された投稿や位置情報のスクラブなどを考慮しない状態) である一方、data エンドポイントは配信時点でコンプライアンスに準拠し、すべてのコンプライアンスイベントを反映しているため、結果に不一致が生じる場合があります。
クエリに一致するはずのポストが取得できません。なぜですか？
クエリに一致するはずのポストが取得できません。なぜですか？
これが起こりうる理由はいくつかあり、たとえば次のとおりです。
- 期待していたポストが非公開アカウントのものである場合
- データエンドポイントではすべてのコンプライアンスイベントが考慮されるため (削除された投稿やジオ情報が削除されたものなどは、レスポンスに含まれません) 。
自分のクエリにマッチしたポストに、除外（否定）したはずのキーワードが含まれていました。これはなぜですか？
自分のクエリにマッチしたポストに、除外（否定）したはずのキーワードが含まれていました。これはなぜですか？
Search ポスト API を使い始める際に利用できるライブラリはありますか？
Search ポスト API を使い始める際に利用できるライブラリはありますか？
はい、あります。例えば次のようなものです。
- Tweepy - 標準的な search/投稿 プロダクトを利用するのに適しています (Python)
- X API - 標準的な Search Post API を利用するのに適しています (Python)
- Search Posts Python と Search Posts Ruby - enterprise (および v2！) の Search Post API で使用できる、便利な 2 つのツールです
データエンドポイントへのリクエストで `maxResults` に指定した値より少ない数の投稿しか返されないことはありますか？
データエンドポイントへのリクエストで `maxResults` に指定した値より少ない数の投稿しか返されないことはありますか？
はい。データエンドポイントは、指定された
maxResults に達するか、30 日が経過した時点のいずれか早い方でページネーションされます。たとえば、ある 30 日間に 800 件の投稿がある場合、すべての結果を取得するには 2 回リクエストを行う必要があります。1 回のリクエストで返せる投稿の最大数は 500 件 (maxResults) だからです。また、1 か月目に 400 件、2 か月目に 100 件の投稿がある場合も、完全な結果を取得するには 2 回のリクエストが必要です。最初のリクエストで指定した maxResults 未満の投稿しか返されなかった場合でも、30 日が経過するとページネーションが行われるためです。一致する投稿はどのような順序で返されますか？
一致する投稿はどのような順序で返されますか？
投稿は新しいものから古いものへと、逆時系列で返されます。たとえば、最初のページにはクエリに一致する最新の投稿が表示され、結果の投稿日時が最初にリクエストした
fromDate に到達するまでページネーションが続きます。投稿の編集は、利用状況や課金にどのような影響がありますか？
投稿の編集は、利用状況や課金にどのような影響がありますか？
課金対象となるのは元のポストだけです。以降の編集は無視され、アクティビティ全体のカウントには加算されません。
EnterpriseEnterprise Search ポスト API の料金について詳しく知りたいのと、このオファリングに申し込みたいと考えています。どのように手続きすればよいですか？
Enterprise Search ポスト API の料金について詳しく知りたいのと、このオファリングに申し込みたいと考えています。どのように手続きすればよいですか？
当社のエンタープライズ向けソリューションは、お客様のビジネスニーズに合わせて、料金を見通しやすい形でカスタマイズされています。詳しくは、こちら からお申し込みください。
自分のユースケースに合ったルールセットを作成するにはどうすればよいですか？
自分のユースケースに合ったルールセットを作成するにはどうすればよいですか？
今月分のリクエスト上限を超えてしまいましたが、さらに多くのデータにアクセスする必要があります。どうすればよいですか？
今月分のリクエスト上限を超えてしまいましたが、さらに多くのデータにアクセスする必要があります。どうすればよいですか？
この件については、Xの担当アカウントマネージャーまでお問い合わせください。
エラー対処ガイド
- 各エンドポイントに対して適切なパラメータを使用していることを確認してください (例：
bucketsフィールドは counts エンドポイントでのみ使用でき、data エンドポイントでは使用できません) :product、:account_name、:labelフィールドが正しいことを再度確認してください。:labelフィールドは GNIP コンソール (エンタープライズ顧客のみ) で確認できます。
APIリファレンス
Enterprise search APIs
- 30-Day Search API - 過去 30 日間に投稿されたツイートを提供します。
- Full-Archive Search API - 2006 年 3 月に投稿された最初のツイート以降のツイートを提供します。
- ツイートデータおよび件数をリクエストするメソッド
- 認証
- ページネーション
- API リクエストパラメータとリクエスト例
- API レスポンスの JSON ペイロードとレスポンス例
- HTTP レスポンスコード
メソッド
https://gnip-api.x.com/search/ です。
| Method | Description |
|---|---|
| POST /search/:product/accounts/:account_name/:label | 指定した PowerTrack ルールに一致する、過去 30 日間のツイートを取得します。 |
| POST /search/:product/accounts/:account_name/:label/counts | 指定した PowerTrack ルールに一致する、過去 30 日間のツイート数を取得します。 |
:productはリクエストを送信する検索エンドポイントを表し、30dayまたはfullarchiveのいずれかです。:account_nameは、console.gnip.com に表示されるアカウントに関連付けられた (大文字・小文字を区別する) 名前です。:labelは、console.gnip.com に表示される検索エンドポイントに関連付けられた (大文字・小文字を区別する) ラベルです。
- データエンドポイント: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod.json
- カウントエンドポイント: https://gnip-api.x.com/search/30day/accounts/TwitterDev/prod/counts.json
:product、:account_name、:label を使用しています。これらの例を利用する際は、ご自身の情報に合わせて URL を更新してください。
認証
リクエスト／レスポンスの挙動
fromDate と toDate パラメータを使用することで、API がサポートする任意の期間をリクエストできます。30-Day search API は直近 31 日分のツイートを提供します (「30-Day」API と呼ばれていますが、ユーザーが完全な 1 か月分をリクエストできるように 31 日分を利用可能にしています) 。Full-Archive search API は、最初のツイート (2006 年 3 月 21 日) までさかのぼってツイートを提供します。ただし、単一のレスポンスに含まれるのは、指定した maxResults または 31 日分のうち小さい方までです。一致するデータ量または指定した時間範囲が、指定した maxResults または 31 日を超える場合、指定した期間の残りの部分をページングするために使用すべき next トークンが返されます。
たとえば、Full-Archive search を使用して、2017 年 1 月 1 日から 2017 年 6 月 30 日までの間でクエリに一致するすべてのツイートを取得したいとします。リクエストでは、fromDate と toDate パラメータを使用して、その 6 か月間全体を指定します。search API は、最初の「ページ」のツイートを返し、そのツイート数は maxResults パラメータ (デフォルトは 100) で指定した数になります。さらにツイートが存在する場合 (通常は存在します) 、API は次のデータ「ページ」をリクエストできるようにする next トークンも返します。この処理は、API が next トークンを返さなくなるまで繰り返されます。詳細については次のセクションを参照してください。
ページネーション
データのページネーション
maxResults パラメータのデフォルト値は 100 で、10～500 の範囲で設定できます。クエリに一致するツイートの数が、リクエストで使用した maxResults パラメータを超える場合、レスポンスには ‘next’ トークン (ルートレベルの JSON 属性) が含まれます。この ‘next’ トークンは後続のリクエストで使用し、そのクエリに一致するツイートの次の部分 (すなわち次の「ページ」) を取得するためのものです。‘next’ トークンは、そのクエリの結果の最後の「ページ」に到達し、‘next’ トークンが返されなくなるまで提供され続けます。
次の「ページ」のデータをリクエストするには、元のクエリとまったく同じクエリを実行する必要があります。必要に応じて query、toDate、fromDate パラメータを含め、さらに前回のレスポンスで返された値を設定した ‘next’ リクエストパラメータも含めます。これは GET リクエストと POST リクエストのいずれでも利用できます。ただし、GET リクエストの場合、‘next’ パラメータは URL エンコードされている必要があります。
クエリの対象期間をカバーするすべてのツイートを受信するまで、前回のクエリで受け取った ‘next’ トークンを引き続き渡すことができます。‘next’ トークンを含まないレスポンスを受信した場合、それは最後のページに到達しており、指定したクエリおよび期間に対して利用できる追加データがないことを意味します。
カウントのページネーション
counts エンドポイントは、クエリに関連付けられたツイート数を、日次、時間単位、または分単位のいずれかの粒度で提供します。counts API エンドポイントは、最大 31 日分のカウントをタイムスタンプ付き配列として返します。31 日を超える期間のカウントをリクエストした場合、next トークンが返されます。データ用の next トークンと同様に、元とまったく同じクエリを送信し、前回のレスポンスで返された値を設定した next リクエストパラメータも含める必要があります。
31 日を超えるカウントをリクエストする場合以外にも、next トークンが提供されるシナリオがあります。ボリュームの大きいクエリでは、カウントの生成に時間がかかり、レスポンスのタイムアウトが発生する可能性があります。この場合、31 日分より少ないカウントしか受け取れませんが、カウントのペイロード全体を取得し終えるまでリクエストを継続できるように、next トークンが返されます。重要: タイムアウトが発生した場合、レスポンスには完全な「バケット」のみが含まれます。そのため、2.5 日分のデータがある場合は、2 日分の完全な「バケット」のみが結果として返されます。
追加の注意事項
- 検索リクエストで fromDate または toDate を使用する場合、取得できる結果は指定した時間範囲内のものだけになります。時間範囲内の結果の最後のグループに到達すると、
nextトークンは返されません。 next要素は、maxResults の値が 10〜500 の任意の値 (デフォルト値は 100) で使用できます。maxResults は各レスポンスで返されるツイート数を決定しますが、最終的にすべての結果を取得することを妨げるものではありません。next要素には有効期限がありません。同じnextクエリを使用した複数のリクエストは、リクエストのタイミングに関係なく同じ結果を受け取ります。nextパラメータを使用して結果をページングする場合、クエリの境界付近で重複が発生することがあります。アプリケーション側でこれらの重複を許容できるようにしておく必要があります。
データエンドポイント
POST /search/:product/:label
エンドポイントパターン:
データリクエストパラメータ
| Parameters | Description | Required | Sample Value |
|---|---|---|---|
| query | 最大 2,048 文字まで指定できる、1 つの PowerTrack ルールと同等の内容を指定します (肯定および否定の句の数に制限はありません) 。 このパラメータには、すべてのオペレーターを含む PowerTrack ルールを構成するすべての要素を含める必要があります。ルールの一部をクエリの他のパラメータに分割しないでください。 注: すべての PowerTrack オペレーターがサポートされているわけではありません。サポートされているオペレーターはこちらに一覧があります。 | Yes | (snow OR cold OR blizzard) weather |
| tag | タグは、ルールおよびそれにマッチしたデータを、異なる論理グループに分けるために使用できます。ルールタグが指定された場合、そのルールタグは ‘matching_rules’ 属性に含まれます。 ルールタグにはルール固有の UUID を割り当て、必要な対応関係はクライアント側で管理することを推奨します。 | No | 8HYG54ZGTU |
| fromDate | ツイートが返される最も古い UTC タイムスタンプ (Full-Archive search の場合は 2006 年 3 月 21 日まで遡及可能) を指定します。タイムスタンプは分単位の粒度で、指定した時刻を含みます (例: 12:00 は 00 分を含みます) 。 指定した場合: toDate パラメータを指定せずに fromDate のみを使用すると、今( ) から fromDate まで過去に遡るクエリ結果が返されます。 指定しなかった場合: fromDate が指定されていない場合、API は今( ) から、または (指定されていれば) toDate から 30 日前までのすべての結果を返します。 fromDate と toDate のどちらのパラメータも使用しない場合、API はリクエスト時点から過去に遡る直近 30 日間のすべての結果を返します。 | No | 201207220000 |
| toDate | ツイートが返される、最も新しい (最新の) UTC タイムスタンプを指定します。タイムスタンプは分単位の粒度で、上限値は含みません (例: 11:59 はその時間の 59 分を含みません) 。 指定した場合: fromDate パラメータを指定せずに toDate のみを使用すると、toDate より前の直近 30 日間のデータが返されます。 指定しなかった場合: toDate が指定されていない場合、API は今( ) から fromDate まで過去に遡る、クエリのすべての結果を返します。 fromDate と toDate のどちらのパラメータも使用しない場合、API はリクエスト時点から過去に遡る、30 日インデックス全体のすべての結果を返します。 | No | 201208220000 |
| maxResults | 1 回のリクエストで返される検索結果の最大数を指定します。10 以上、システム上限 (現在 500) 以下の数値です。デフォルトでは、1 回のリクエストのレスポンスで 100 件の結果が返されます。 | No | 500 |
| next | このパラメータは、こちらで説明されているように、次の「ページ」の結果を取得するために使用されます。パラメータに指定する値は API が返すレスポンスから直接取得したものであり、変更してはいけません。 | No | NTcxODIyMDMyODMwMjU1MTA0 |
追加の詳細
| 利用可能な期間 | 30-Day: 直近31日間 Full-Archive: 2006年3月21日～現在 |
| クエリ形式 | 最大2,048文字までの1つの PowerTrack ルールに相当するクエリ (ポジティブおよびネガティブ句の数に制限はありません) 。 注: すべての PowerTrack 演算子がサポートされているわけではありません。サポートされている演算子の一覧については、Available operators を参照してください。 |
| レート制限 | パートナーには、分単位および秒単位の両方でレート制限が適用されます。1分あたりのレート制限は、契約書に記載されているとおりパートナーごとに異なります。ただし、これらの1分あたりのレート制限は、単一のバーストで消費することを想定したものではありません。1分あたりのレート制限にかかわらず、すべてのパートナーは、データおよび／またはカウントに対するすべてのリクエストを合算した上で、1秒あたり最大20リクエストに制限されます。 |
| コンプライアンス | Full-Archive Search API から配信されるすべてのデータは、配信時点においてコンプライアンス要件に準拠しています。 |
| リアルタイム性 | データは、Twitter プラットフォーム上で生成されてから30秒以内にインデックスに反映され、利用可能になります。 |
データリクエストとレスポンスの例
POST リクエストの例
- POST リクエストのパラメータは、以下のように JSON 形式のボディで送信されます。
- 取得対象の PowerTrack ルールのすべての部分 (例: キーワード、bounding_box: のようなその他のオペレーター) は、‘query’ パラメータに含める必要があります。
- ルールの一部をクエリ URL 内の別々のパラメータとして分割しないでください。
GET リクエストの例
- GET リクエストのパラメータは、標準的な URL エンコードを用いて URL にエンコードされます。
- クエリ対象となる PowerTrack ルールのすべての要素 (例: キーワード、
bounding_box:のような他のオペレーター) は、queryパラメータに含める必要があります。 - クエリ URL 内で、ルールの一部を個別のパラメータとして分割しないでください。
データレスポンスの例
カウント用エンドポイント
/search/:stream/counts
エンドポイントパターン:
/search/fullarchive/accounts/:account_name/:label/counts.json
このエンドポイントは、指定されたクエリに対するカウント (データボリューム) データを返します。期間が指定されていない場合、時間パラメーターのデフォルトは直近30日間になります。データボリュームは、日単位、時間単位 (デフォルト) 、または分単位のいずれかで、タイムスタンプ付き配列として返されます。
注: この機能は、以下で説明するパラメーターを URL にエンコードすることで、POST ではなく GET リクエストを使用して実行することもできます。
カウントリクエストのパラメータ
| Parameters | Description | Required | Sample Value |
|---|---|---|---|
| query | 1 つの PowerTrack ルールに相当するクエリで、最大 2,048 文字まで指定できます (肯定/否定の句の数に制限はありません) 。 このパラメータには、すべてのオペレーターを含む PowerTrack ルールのすべての要素を含める必要があり、ルールの一部を query の別パラメータに分割してはいけません。 注: すべての PowerTrack オペレーターがサポートされているわけではありません。サポートされているオペレーターの一覧については、Available operators を参照してください。 | Yes | (snow OR cold OR blizzard) weather |
| fromDate | ツイートが提供される最も古い UTC タイムスタンプ (2006 年 3 月 21 日まで遡ることができます) 。タイムスタンプは分単位の精度で、下限値を含みます (例: 12:00 は 00 分を含みます) 。 指定した場合: toDate パラメータを指定せずに fromDate のみを使用した場合、API は現在から fromDate まで遡って、クエリのカウント (データ量) データを返します。fromDate が現在から 31 日を超えて過去の場合、リクエストをページングするための next トークンが返されます。 指定しない場合: fromDate を指定しない場合、API は現在 ( ) または toDate (指定されている場合) を基準として、その 30 日前まで遡ったカウント (データ量) を返します。 fromDate と toDate のどちらのパラメータも使用しない場合、API はリクエスト時点から遡って直近 30 日間のカウント (データ量) を返します。 | No | 201207220000 |
| toDate | ツイートが提供される最も新しい (最新の) UTC タイムスタンプ。タイムスタンプは分単位の精度で、上限値は含みません (例: 11:59 はその時間の 59 分目を含みません) 。 指定した場合: fromDate パラメータを指定せずに toDate のみを使用した場合、toDate から 30 日前まで遡った最新のカウント (データ量) が返されます。 指定しない場合: toDate を指定しない場合、API はクエリについて fromDate まで遡ったカウント (データ量) を返します。fromDate が現在から 31 日を超えて過去の場合、リクエストをページングするための next トークンが返されます。 fromDate と toDate のどちらのパラメータも使用しない場合、API はリクエスト時点から遡って直近 30 日間のカウント (データ量) を返します。 | No | 201208220000 |
| bucket | カウントデータが提供される時間単位です。指定した期間内の毎日、毎時、または毎分のカウントデータを返すことができます。デフォルトでは毎時のカウントが返されます。指定可能な値: ‘day’, ‘hour’, ‘minute’ | No | minute |
| next | このパラメータは、HERE で説明しているように、結果の次の「ページ」を取得するために使用します。このパラメータに使用する値は、API から返されるレスポンスから直接取得するものであり、変更してはいけません。 | No | NTcxODIyMDMyODMwMjU1MTA0 |
追加の詳細
| 利用可能な期間 | 30-Day: 直近31日間 Full-Archive: 2006年3月21日 〜 現在 |
| クエリ形式 | 1つの PowerTrack ルールに相当し、最大2,048文字まで。 注: すべての PowerTrack オペレーターがサポートされているわけではありません。サポートされているオペレーターの一覧は、Available operators を参照してください。 |
| レート制限 | パートナーには、分単位および秒単位の両方でレート制限が適用されます。1分あたりのレート制限は、契約で規定されているとおりパートナーごとに異なります。ただし、これらの1分あたりのレート制限は、単一のバーストで使い切ることを想定したものではありません。1分あたりのレート制限の値にかかわらず、すべてのパートナーは、データおよび/またはカウントに対する全リクエストを合算したうえで、1秒あたり最大20リクエストに制限されます。 |
| カウント精度 | このエンドポイントから提供されるカウントは、発生したツイート数を反映したものであり、その後のコンプライアンスイベント (削除、位置情報のスクラブなど) は反映しません。カウントに含まれていても、ユーザーのコンプライアンスアクションにより、データエンドポイントからは取得できないツイートが含まれている場合があります。 |
カウント用リクエストとレスポンスの例
POST リクエストの例
- POST リクエストのパラメータは、以下のように JSON 形式のボディで送信されます。
- クエリ対象とする PowerTrack ルールのすべての要素 (例: キーワード、bounding_box: のようなその他のオペレーター) は、‘query’ パラメータに含めて指定してください。
- ルールの一部を、クエリ URL の別個のパラメータとして分割しないでください。
GET リクエストの例
- GET リクエストのリクエストパラメータは、標準的な URL エンコード方式で URL にエンコードされます
- クエリ対象の PowerTrack ルールのすべての要素 (例: キーワード、bounding_box: のようなその他のオペレーター) は、‘query’ パラメータに指定してください
- ルールの要素を分割して、query URL 内の別々のパラメータとして指定しないでください
カウントレスポンスの例
HTTP response codes
| Status | Text | Description |
|---|---|---|
| 200 | OK | リクエストは成功しました。JSON レスポンスは次の例と同様の形式になります。 |
| 400 | Bad Request | 通常、このレスポンスは、リクエスト内に無効な JSON が含まれている場合、または JSON ペイロードがまったく送信されなかった場合に返されます。 |
| 401 | Unauthorized | 無効な認証情報により HTTP 認証に失敗しました。お使いの認証情報で console.gnip.com にログインし、リクエストで正しく使用していることを確認してください。 |
| 404 | Not Found | リクエストが送信された URL にリソースが存在しません。誤った URL が使用されている可能性があります。 |
| 422 | Unprocessable Entity | クエリ内のパラメータが無効な場合に返されます (例: 無効な PowerTrack ルール) 。 |
| 429 | Unknown Code | アプリケーションが接続リクエスト数の上限を超過しました。対応する JSON メッセージは次の例と同様の形式になります。 |
| 500 | Internal Server Error | サーバー側でエラーが発生しました。指数バックオフ方式を用いてリクエストを再試行してください。 |
| 502 | Proxy Error | サーバー側でエラーが発生しました。指数バックオフ方式を用いてリクエストを再試行してください。 |
| 503 | Service Unavailable | サーバー側でエラーが発生しました。指数バックオフ方式を用いてリクエストを再試行してください。 |