Rednote Search Notes
Rednoteのノート検索結果は、キーワードに一致した公開投稿で、ノートID、テキスト、投稿者情報、メディア、公開日時、表示中のエンゲージメントを含みます。これらのレコードは、トピック調査、フォーマットの比較、ソースの確認、特定時点の検索結果分析に活用できます。
Rednote Search Notes API の主な機能
- 3種類のフィルターを備えたキーワード検索テキストの検索語1つに加え、対応する並び順、メディア種別、公開期間を選択して、対象を絞った公開ノート検索を定義できます。
- 正規化されたノートIDとコンテンツノートID、公開URL、テキスト、リソース種別、公開日時、取得日時を共通の PostItem 構造で返します。
- 投稿者、メディア、表示中のエンゲージメント取得可能な公開投稿者フィールド、画像または動画の参照、ハッシュタグ、メンション、表示中のいいね数・コメント数・シェア数・再生数を保持します。
- 範囲を限定したソース検索ページタスクごとに選択した検索の1ページ目を1回実行します。複数ページにわたる網羅的なソースクロールではなく、範囲の明確なスナップショットを生成します。
Rednote Search Notes API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
query | 必須 | 必須。公開Rednoteノートの検索に使う空でないテキストです。Playgroundでは、独自の検索語を入力するまで空欄のままです。 |
sort_by | 任意 | 任意。結果の並び順で、general、latest、most_liked のいずれかです。Playgroundの初期値は general です。 |
media_type | 任意 | 任意。ノート形式のフィルターで、all、image、video のいずれかです。Playgroundの初期値は all です。 |
published_within | 任意 | 任意。公開期間のフィルターで、all、day、week、six_months のいずれかです。Playgroundの初期値は all です。 |
Rednote Search Notes API の使い方
Rednoteの検索語と任意のフィルターを送信して非同期タスクを追跡し、保存されたノートレコードをSocQのカーソルページネーションで読み取ります。
- 空でない query を用意し、sort_by、media_type、published_within にはサポートされている値のみを選択します。
- ペイロードを /v1/rednote/search-notes に POST し、返された task_id を保存します。
- タスクが成功するか失敗を返すまで、/v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、has_more が true の間は next_cursor をたどります。これは保存済みの結果をページ送りするもので、Rednoteの検索ページを追加で取得するものではありません。
curl -X POST "https://api.socq.ai/v1/rednote/search-notes" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"query\":\"$REDNOTE_SEARCH_QUERY\",\"sort_by\":\"general\",\"media_type\":\"all\",\"published_within\":\"all\"}"
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueRednote Search Notes API の主なユースケース
- キーワード検索結果のカタログ化: ノートID、公開URL、テキスト、投稿者の参照、collected_at を使い、特定の検索語について追跡可能なスナップショットを作成します。
- 画像と動画の検索結果比較: media_type を変えてそれぞれ実行し、得られたスナップショット間で返されたメディア参照、ノートのテキスト、表示中のエンゲージメントを比較します。
- 新しさを重視したトピック確認: latest の並び順や公開期間のフィルターを published_at、collected_at と組み合わせ、1つのトピックについて最近表示されたノートを確認します。
- 投稿者のコンテキスト分析: 一致したノートのテキストやメディアを取得可能な投稿者情報フィールドと関連付け、検索スナップショットにどの公開アカウントが現れるかを分析します。
Rednote Search Notes API 活用のヒント
- 必須フィールドの検証でタスクが拒否されないよう、送信前に query の前後の空白を除去し、空でないことを確認してください。
- 記載されている列挙値のみを使用してください。明示的に設定したうえで最も広い範囲を検索したい場合は、general、all、all を選択します。
- 各タスクはソース検索1ページ分として扱い、スナップショットが後続のソースページまで含むとは想定せず、フィルターの組み合わせごとに別のタスクを実行してください。
- 保存されたスナップショットがSocQの結果ページで複数ページにわたる場合は、has_more が false になるまで next_cursor をたどってください。このカーソルがRednoteの別のソースページを要求することはありません。
- 取得時刻によって並び順や表示中の指標が異なる場合があるため、別々の検索実行結果を照合する際はノートIDとURLを使用してください。
- テキスト、投稿者フィールド、メディア、公開日時、ハッシュタグ、メンション、個々の指標は null になり得るものとして扱い、公開テキストは表示前にエスケープしてください。
関連API
Rednote Search Notes API 以外に別の種類の公開Rednoteデータが必要な場合は、これらのAPIをご利用ください。