Developer Note
取得・集計ロジック
ユーザー向けマニュアルから外した実装寄りのメモです。秘密情報やトークンは記載しません。X API Full-Archive Search / Counts の取得式
過去ヒット分析では、X API v2 Full-Archive Search と Full-Archive Counts を使います。Bearer TokenはSecret Managerから読み込み、ページやログには出しません。
| 対象 | 現在の考え方 | 例 |
|---|---|---|
| テーマ | テーマ名、productMatchTerms、tagsを最大5語まで使い、OR条件で広めに取得。日本語投稿に限定し、リポストを除外。 | ("カヌレ" OR "半熟カヌレ" OR "生カヌレ") lang:ja -is:retweet |
| 商品 | 商品名、ブランド名＋商品名、メーカー名＋商品名、主要語句セットを最大4クエリまで試す。先に投稿数または投稿サンプルが取れた条件を採用。 | ("ローソン バスチー" OR "バスチー") lang:ja -is:retweet |
| 長い商品名 | 完全一致だけでは拾えないため、主要語句を抽出して複数語のAND寄り条件を試す。 | ("エゾシカ" "熟成舞茸" "赤ワイン") lang:ja -is:retweet |
投稿サンプルの選び方
X API Searchの返却データから public_metrics を読み、反応が大きい投稿だけに偏らないよう複数の観点で混ぜています。
| 枠 | 割合 | 目的 |
|---|---|---|
| 高反応の通常投稿 | 約35% | 生活者に強く反応された投稿を残す。 |
| 初期投稿 | 約25% | 流行の立ち上がりを確認する。 |
| 最近の通常投稿 | 約25% | 現在も話題が残っているかを見る。 |
| 低〜中反応の通常投稿 | 約10% | 反応が強い投稿だけに偏らないようにする。 |
| キャンペーン投稿 | 約5% | 販促反応との比較用に残す。 |
Rakko Keyword API の取得式
- Rakko Keyword APIのサジェスト、関連キーワード、Q&A取得を使う。
- 商品は、ブランド名＋商品名、商品名、主要語句セット、テーマ名＋主要語句を候補にする。
- テーマは、テーマ名を中心にサジェスト、関連語、Q&Aを取得する。
- サジェストモードは現在
google,youtube,amazon,rakutenを使う。 - 比較・検討ワードは、比較、違い、おすすめ、口コミ、評判、どこで売ってる、価格、使い方、レシピなどの意図語で判定する。
- 検索ボリュームが0でも、比較・検討ワードが取れた場合は「検討の兆し」として保持する。
Trend Intelligence Metadata MVP
予測ラボ用の成功要因メタデータは、まず既存のトレンドアーカイブを壊さずに別ファイルへ構造化します。X API、Rakko Keyword API、Cloud Scheduler、BigQuery書き込みはこの処理では実行しません。
| 項目 | 内容 | 保存先 |
|---|---|---|
| 実行コマンド | npm run archive:build-intelligence -- --fetch-sources=true --theme-limit=5 --product-limit=20 |
最初は5テーマ・20商品だけURLメタデータをテスト取得する。 |
| 全量メタデータ | trend_themes、trend_products、trend_sources、trend_metrics、trend_scores、trend_evidence、trend_reviews を保存する。 |
data/generated/trend-intelligence-metadata.json。本番ページには直接読ませない。 |
| 表示用サマリー | 予測ラボとトレンドアーカイブ画面で使う軽量版。テーマ、上位特徴量、類似候補、レビュー待ちを絞って持つ。 | data/generated/trend-intelligence-summary-data.js |
| レビューキュー | 公式情報不足、価格・発売日不明、根拠弱いスコア、外部反応未取得などを人間レビュー待ちとして出す。 | data/generated/trend-intelligence-review-queue.csv |
| 収集ログ | 参照元URLの取得成功/失敗、HTTPステータス、失敗理由、取得日時を残す。 | data/generated/trend-intelligence-collection-log.json |
| 成功済みURL固定キャッシュ | 一度取得できた参照元URLのタイトル、説明、画像、抽出フィールドを固定する。再実行時は成功済みURLを再取得せず、失敗・欠損だけを処理する。 | data/generated/trend-intelligence-source-cache.json |
| 代替URL | 旧URL、移転、404、アクセス遮断で取得できない参照元だけ、公式現行URLや公開リリースなどの代替URLを明示して取得する。代替理由も保存する。 | data/generated/trend-intelligence-source-replacements.json |
| 外部補助値 | npm run archive:enrich-secondary で、公式・既存メタデータが空欄の項目だけを公開補助ソースから探す。成功済みの値は上書きしない。App Storeの公開検索結果は価格・発売日・販売元の補助候補に使い、EC検索価格は公式価格ではなく external_market_price として分けて保存する。 |
data/generated/trend-intelligence-secondary-facts.json、trend-intelligence-secondary-cache.json、trend-intelligence-secondary-quality-report.json |
| 公開検索ワード計画 | node scripts/build-trend-intelligence-search-plan.mjs で、残欠損の商品・サービスごとに完全一致、分解一致、ソース寄せの複数検索語を作る。店舗・時期・サイズ差は caveat に残し、近い商品やシリーズと混同しそうな場合は user_confirmation_required として候補反映前に止める。 |
data/generated/trend-intelligence-public-search-plan.json、trend-intelligence-public-search-plan.md、trend-intelligence-user-confirmation-required-20260626.json |
| 欠損分類 | npm run archive:classify-missing で、残っている価格・発売日・ブランド/会社名の欠損を分類する。単純に埋めるべき欠損、サービスやテーマ粒度で項目概念が薄いもの、外部EC価格を参考値として持つものを分ける。 |
data/generated/trend-intelligence-missing-review-classification.csv、.json、.md |
現在の取得上限
| 対象 | 上限 | 備考 |
|---|---|---|
| アーカイブ商品 | 最大500投稿 / 商品 | 高精度分析用。429が出たら保存済み地点から再開する。 |
| アーカイブテーマ | 最大300投稿 / テーマ | 大テーマは投稿数が大きく出るため、後から細テーマ化を検討する。 |
| Rakko Keyword API | 候補語・関連語・Q&Aを各キーワードで取得 | クレジット消費があるため、手動実行はユーザー承認後に行う。 |
運用注意
- 開発中にCloud Scheduler、通常市場収集、X API、Rakko Keyword API、YouTube Data API、Social Insight、BigQuery load、メール送信を勝手に実行しない。
- ユーザーが明示的に承認した場合だけ、有料APIやクレジット消費のある処理を実行する。
- Secret Managerの値、Bearer Token、APIキーは画面・チャット・ファイルに再掲しない。
- UIやマニュアルの変更だけなら、収集ジョブは動かさず、生成済みデータと公開ファイルで確認する。