基本概念
モモンガサーチ API の主要リソースと、複数のエンドポイントで使う判断フィールドを整理します。
documents
企業公表資料を表すリソースです。v1 では主に次の分類を扱います。
| 分類 | 例 |
|---|---|
edinet_filing | 有価証券報告書、四半期報告書など |
timely_disclosure | 決算短信、業績予想修正、中期経営計画など |
ir_material | 企業公式サイトで公開される決算説明資料、月次資料など。v1 ではメタデータのみ |
document_id は opaque な安定 ID です。中身を解釈せず、そのまま保存してください。
GET /v1/documents の document_families では edinet_filing、timely_disclosure、ir_material を指定できます。POST /v1/search/documents の document_families で使える値は edinet_filing と timely_disclosure です。ir_material は一覧やメタデータでは返りますが、v1 の文書本文検索では対象外です。
document_types は文書種別で絞り込むための値です。v1 では主に yuho、tanshin、other を使います。
news
ニュース記事本文ではなく、根拠参照先を伴う正規化済みの更新情報です。文書検索とは別に扱います。
GET /v1/news は新着 news の発見に使うタイムライン API で、各 item に references[] を含みます。POST /v1/search/news は自然文クエリで news を探す API で、NewsItem に score を加えたヒットを返します。どちらも 1 request = 1 credit です。
public API は記事本文を返さず、利用者に渡す最小単位として statement を返します。根拠確認には news 専用の references[] を使います。references[] には URL またはモモンガサーチ API の document_id が入ります。
主なフィールド:
| フィールド | 意味 |
|---|---|
news_id | 1 statement に対応する stable ID |
statement | 正規化された更新情報 |
observed_at | モモンガサーチ API が観測した時刻 |
related_issuers[] | 関連 issuer。link_basis で解決根拠を示す。alias_match は抽出済み issuer 名の alias 辞書解決であり、statement 本文全体の部分一致ではありません |
references[] | news statement の根拠参照先。document.reference_url とは別仕様 |
parent_news_id | 同じ話題スレッド上の直前の news。訂正・否定・置換を意味しない |
macro_tags[] | 市場全体に関わる news を絞り込むためのマクロ事象カテゴリ。documents の tags とは別仕様 |
public v1 の macro_tags は次の 7 分類です。API の値は英語 enum ですが、右側の日本語ラベルを表示名として扱えます。
| API value | 日本語ラベル | 意味 |
|---|---|---|
Economic Indicators | 経済指標 | 雇用統計、GDP、CPI、PMI などの公表マクロ統計 |
Monetary Policy | 金融政策 | 中央銀行の政策金利、資産買入、為替介入、流動性供給など |
Fiscal Policy | 財政政策 | 政府予算、税制改正、国債発行、補正予算、財政出動など |
Regulatory Policy | 規制・制度 | 業法改正、セクター規制、規制当局の措置・許認可、制裁など |
Trade & Geopolitical Events | 通商・地政学 | 関税、通商交渉、貿易摩擦、国家間の紛争・外交・条約、選挙結果など |
Financial Stability | 信用不安 | 金融機関のストレス、デフォルト、格下げ、信用事由、流動性ショックなど |
External Shocks | 外生ショック | 資源価格ショック、サプライチェーン途絶、自然災害、パンデミックなど |
現行 v1 では documents と news の横断検索 API はありません。文書本文を探す場合は POST /v1/search/documents、更新情報を探す場合は POST /v1/search/news を呼び分けます。
published_at、first_observed_at、timeline_at
モモンガサーチ API では、公式公表時刻、観測時刻、一覧・検索用タイムラインを分けています。
| フィールド | 意味 |
|---|---|
first_observed_at | モモンガサーチ API が文書を最初に観測した時刻 |
published_at | 公式な公表・提出時刻。未確定時は null |
timeline_at | 一覧・検索・timeline_since / timeline_until フィルタに使う正規化時刻。公式時刻とは限らず、公式メタデータ、文書表面・リンクラベルからの推定日付、または観測時刻のいずれか |
timeline_precision | timeline_at の精度。時刻まで確定している場合は datetime、日付単位の場合は date |
timeline_basis | timeline_at の根拠。official は公式メタデータ、inferred は文書表面・リンクラベルなどからの推定、observed はモモンガサーチ API の観測時刻 |
timeline_basis=observed の行は、文書日付を確定できず観測時刻でタイムラインに載せていることを表します。文書日付だけを扱いたい場合は timeline_basis=observed の行を除外します。公式な公表・提出時刻だけが必要な場合は published_at を使います。
上流データ提供元の再配信条件により、適時開示文書では開示後 24 時間以内に公開 API へ返せる情報が制限される場合があります。その場合、published_at=null のまま、企業公式サイトから独立に確認できたメタデータと reference_url だけを返すことがあります。
content_status
文書本文、目次、API から取得できる元ファイルの可否は content_status で判断します。
| 値 | 意味 | 次のアクション |
|---|---|---|
ready | 本文・目次を取得できる | /toc で取得単位を確認し、必要な section_id だけ /content で取得する |
pending_release | 公開制約などにより一時的に本文を返せない | retry_after_seconds を見て再試行する |
external_only | API では本文を配信せず、外部発信元の確認用 URL だけを返す | reference_url を表示する |
pending_release と external_only はどちらも content_available=false ですが、扱いが異なります。
pending_release は、本文・目次・検索 snippet を API で返せる状態になる見込みがある一時状態です。適時開示の公開制約や、公開用 content の準備待ちがある場合に使います。クライアントは retry_after_seconds を見て再試行できます。
external_only は、モモンガサーチ API が本文を配信しないメタデータのみの状態です。企業公式サイト上の外部資料などが該当します。本文取得を繰り返さず、reference_url で外部発信元を確認してください。
この分離により、「あとで同じ API を再試行する文書」と「外部確認に切り替える文書」を機械的に区別できます。公式公表時刻、観測時刻、本文配信可否も混同せずに扱えます。
対応データの期間、最新開示の反映、企業公式サイトで公開された資料メタデータの扱いは データ対応範囲 を参照してください。
セクション選択
GET /v1/documents/{document_id}/toc は、/content?sections=... で指定できる本文取得単位を返します。紙面や PDF 上の全見出しを列挙するものではありません。
主なフィールド:
| フィールド | 意味 |
|---|---|
section_id | /content?sections=... に渡す opaque selector。検索結果の matches[].section_id と同じ仕様 |
section_title | 表示用のセクション名 |
heading_path | 文書 root からそのセクションまでの見出し階層。表示、曖昧性解消、Agent の判断に使う |
character_count | そのセクションの正規化本文の文字数。LLM や分析処理に渡す前のサイズ見積もりに使う |
page_number | PDF 由来文書で分かる場合の開始ページ。ページ画像の取得可否は /page-images で確認する |
section_id は selector として保存してください。heading_path は人間や Agent がセクションの意味を判断するためのメタデータであり、一意な selector の代替ではありません。同じ見出しが文書内に複数回出る場合も、section_id で区別します。
本文 format
GET /v1/documents/{document_id}/content は、常に content という 1 つの文字列を返します。sections を指定した場合も同じです。セクション単位で扱いたい場合は content_sections[] を使います。
content_format は文書により text または markdown です。TDNet PDF や説明資料など、表・見出し・箇条書きの構造を残した方が扱いやすい資料では markdown になる場合があります。固定値を仮定せず、content_format を見て後続処理を分岐してください。
ページ画像
page_count は、PDF ページ単位で提供している文書で総ページ数を判定できた場合に返します。ページ単位で提供していない文書や、ページ数が未判定の文書では省略される場合があります。
image_available=true は、visual / VLM 検証用に取得できるページ画像が 1 枚以上あることを表します。すべてのページ画像が取得可能であることや、page_count が常に返ることは意味しません。
page_image_count は、API から取得できるページ画像数です。ページ画像がない文書や、取得可能範囲が未判定の文書では省略される場合があります。
取得可能なページ番号は GET /v1/documents/{document_id}/page-images で確認してください。GET /v1/documents/{document_id}/pages/{page_number}/image は、/page-images に含まれるページだけ JPEG を返します。
元ファイル
reference_url は外部発信元を確認するための URL です。外部サイトの構成変更や参照元補完により、より適切な確認先へ更新される場合があります。PDF / ZIP などの元ファイルを機械的に取得するための安定したダウンロード URL ではありません。
reference_url は documents のフィールドです。news の根拠参照先は references[] として別に定義され、{type: "url", url} または {type: "document", document_id} を返します。document.reference_url を news の根拠保証として扱ったり、news.references[] を文書のダウンロード URL として扱ったりしないでください。
originals はモモンガサーチ API から取得できる元ファイルの一覧です。PDF、XBRL ZIP、iXBRL ZIP など、文書によって複数の元ファイルが存在する場合があります。
API ワークフローでは、正規化本文は GET /v1/documents/{document_id}/content、API が保持する元ファイルは GET /v1/documents/{document_id}/originals を使います。ファイル取得時は、一覧内の original_id を GET /v1/documents/{document_id}/originals/{original_id} に渡します。PDF / XBRL ZIP など複数の元ファイルがある場合は、kind / media_type / role を見て用途に合うものを選びます。