モモンガサーチAPI

典型的な使い方

代表的なワークフローです。

LLM や分析コードに渡す基本方針

LLM、Agent、自作ワークフロー、特徴量抽出コードでは、いきなり全文を読まず、次の順で対象を絞る設計を推奨します。

  1. GET /v1/documents?security_codes=... または GET /v1/documents?timeline_since=... で候補文書を探す
  2. POST /v1/search/documents で該当箇所を探す
  3. content_status を確認する
  4. ready なら /toc で section_id、heading_path、character_count を確認する
  5. 必要な section_id だけ /content?sections=... で取得する

content_status=pending_release はあとで再試行し、external_only は外部確認に切り替えます。API から取得できる元ファイルが必要な場合は、GET /v1/documents/{document_id}/originals で確認します。

Agent runtime で使う場合の推奨設計

Claude Code / Codex などの agent runtime からモモンガサーチ API を使う場合、API レスポンスや /content の本文を、そのまま長文でモデルの会話コンテキストに流し続ける設計は推奨しません。

通常の HTTP 呼び出し結果は、組み込みの Web 検索 tool のように、runtime 側で自動的に要約・抽出されません。API レスポンスや本文をモデルに渡す場合、その内容は会話コンテキストに入る前提で設計してください。長い本文を一度モデルに渡すと、その後の会話や実装作業でも context window と token budget を圧迫する可能性があります。

そのため、Agent / tool / harness 側で、モデルに渡す情報量を制御する設計を推奨します。

推奨する流れ:

  1. /documents、/search/documents、/toc で候補文書とセクションを絞る
  2. character_count で、モデルに渡す本文量を事前に見積もる
  3. /content?sections=... では必要な section_id だけ取得する
  4. 長い本文はローカルファイルやデータストアに保存し、モデルには必要箇所の抜粋・要約・参照 ID を渡す
  5. 複数文書を比較する場合は、各文書を短い根拠メモに圧縮してから統合する

モモンガサーチ API は、一次情報を検索・取得しやすくするための API です。取得した情報のうち、どこまでをモデルに渡すか、どの粒度で要約するか、何を会話コンテキストに残すかは、利用側の agent / harness で制御する設計を推奨します。

必要な本文を絞り込む例

複雑な投資判断を、そのまま検索クエリにする設計は推奨しません。モモンガサーチ API では根拠候補を疑問文で探し、取得した本文を Agent や LLM に渡して判断します。

callerreceiver
Agent
モモンガサーチ API
GET /v1/documents?security_codes=8058&limit=10
モモンガサーチ API
Agent
document_id, title, content_status, reference_url
Agent
モモンガサーチ API
POST /v1/search/documents query="原材料価格の上昇をどのように価格転嫁していますか？" match_type="semantic" include_snippet=true
モモンガサーチ API
Agent
matches[].section_id, snippet, score
Agent
モモンガサーチ API
GET /v1/documents/{document_id}/toc
モモンガサーチ API
Agent
toc[].section_id, heading_path, character_count
Agent
モモンガサーチ API
GET /v1/documents/{document_id}/content?sections=...
モモンガサーチ API
Agent
正規化本文, character_count, reference_url
Agent
LLM / 分析コード
価格転嫁が粗利率改善に効くか、本文だけを根拠に整理

この例で Agent が考える問いは「価格転嫁が粗利率改善に効くか」です。一方、モモンガサーチ API に渡す semantic 検索クエリは 原材料価格の上昇をどのように価格転嫁していますか？ のような、根拠候補を探す疑問文にします。API は答えを作る場所ではなく、答えに必要な一次情報を取り出す場所です。

複数社の有報からテーマを比較する

  1. GET /v1/issuers/search で証券コードを特定する
  2. GET /v1/documents?security_codes=... で各社の最新有報を探す
  3. POST /v1/search/documents に自然文クエリを送る
  4. 検索結果の document_id と section_id を使って /content を取得する
  5. 取得した一次情報だけを LLM に渡して比較レポートを生成する

semantic 検索クエリは、原材料価格の上昇をどのように価格転嫁していますか？、在庫評価についてどのようなリスクを説明していますか？ のような疑問文にします。短い観点語で探す場合は match_type: "lexical" を明示します。投資判断は、取得した本文を LLM や分析コードに渡した後の問いとして扱います。

テキスト特徴量として使う

  1. GET /v1/documents?security_codes=... または GET /v1/documents?timeline_since=... で対象期間と銘柄の文書を探す
  2. POST /v1/search/documents で分析したい観点に近いセクションを探す
  3. matches[].section_id を使って /content?sections=... で本文を取得する
  4. 取得した正規化テキストを embedding、分類器、スコアリング、イベント検知などの入力にする
  5. document_id、section_id、published_at、reference_url を保存して、後から根拠に戻れるようにする

大量の全量取得ではなく、検索結果や目次で対象セクションを絞ってから本文を取得する設計を推奨します。特徴量の再現性が必要な場合は、使った document_id と section_id を保存します。

TDNet PDF のグラフを読む

  1. POST /v1/search/documents で document_types: ["other"] を指定して、TDNet で公開された決算説明資料・補足資料などを探す
  2. image_available=true なら、ページ画像を取得できる候補として扱う
  3. GET /v1/documents/{document_id}/page-images で取得可能なページ番号を確認する
  4. 必要なページを /pages/{page_number}/image で取得する
  5. 画像を VLM に渡す

ページ画像を取得する場合は、page_count の有無にかかわらず /page-images で取得可能なページ番号を確認してください。/page-images に含まれないページを /pages/{page_number}/image で取得しようとすると 409 image_not_available が返ります。

PDF / ZIP の元ファイルを確認する

  1. GET /v1/documents/{document_id}/originals で取得可能な元ファイルを確認する
  2. original_available=true なら、必要な original_id を選ぶ
  3. GET /v1/documents/{document_id}/originals/{original_id} で PDF / ZIP を取得する
  4. 監査、社内保存、レイアウト確認、既存 VLM pipeline などに渡す

reference_url は外部発信元の確認用であり、元ファイルのダウンロード URL ではありません。API から取得できる元ファイルは originals で確認し、取得可能なものだけファイル取得エンドポイントを呼んでください。

新着開示をポーリングする

GET /v1/documents?timeline_since=... は 0-credit API です。文書の新着確認のためのポーリングで credits は消費しません。

GET /v1/news?timeline_since=... は references[] 付きの news statement を返す credit API です。news の新着確認は 1 request = 1 credit を消費します。

ただし、0 credits は無制限を意味しません。市場全体の一覧取得では timeline_since が必要です。全量走査や高頻度同期はリクエスト上限 / fair-use review の対象になります。

公開プランごとの毎分リクエスト数、日次リクエスト上限、credit API の credits は Pricing のプラン表を参照してください。429 が返ったら Retry-After を尊重し、exponential backoff と jitter を入れて再試行します。429 を無視した継続リクエスト、bulk export、mirroring、高頻度同期は API キーの制限や個別契約への移行対象になります。

API レスポンスには X-Quota-Catalog-Remaining / X-Quota-Catalog-Reset、X-Quota-Compute-Remaining / X-Quota-Compute-Reset を返します。Compute の reset は Trial では Trial 終了時刻、Plus / Pro では契約更新時刻です。

ポーリングでは、同じ時間範囲を秒単位で連打しないでください。前回の timeline_since を保持し、通常時は数十秒から数分程度の間隔を空けます。ページネーションでは next_cursor を使い、同じページを繰り返し取得しないでください。

経済ニュースを AI に渡す

  1. GET /v1/news?security_codes=...、GET /v1/news?timeline_since=...、または GET /v1/news?macro_tags=... で新着 news を取得する
  2. POST /v1/search/news に自然文クエリを投げる。必要に応じて security_codes、timeline_since / timeline_until、macro_tags で絞り込む
  3. statement を AI に渡す
  4. references[] で根拠参照先を表示する
  5. parent_news_id がある場合は、同じ話題スレッドの前後関係として扱う

news は documents の本文ヒットとは別の検索対象です。記事本文を取得する API ではなく、根拠参照先付きの更新情報リソースとして扱ってください。news.references[] と documents の reference_url は別仕様です。

credits 消費を抑える

  • /toc は credits を消費しません。先に目次と character_count を確認します。
  • GET /v1/news と POST /v1/search/news はどちらも references[] 付きの news statement を返すため、1 request = 1 credit です。
  • /content は返す本文量により 2 / 4 / 8 credits を消費します。sections を指定して必要な節だけ取得します。
  • ページ画像は 1 page = 1 credit です。/page-images で取得可能ページを確認してから必要なページだけ取得します。
  • 元ファイルは 1 file = 8 credits です。/originals で取得可能ファイルを確認してから必要なファイルだけ取得します。
  • 2xx レスポンスのみ credits 消費対象です。4xx / 5xx / 429 は消費しません。