データ対応範囲と鮮度
モモンガサーチ API では、文書の発見、本文検索、本文取得、元ファイル取得、ページ画像取得を別々の機能として扱います。
GET /v1/documents に出る文書が、常に全文検索や /content の対象になるとは限りません。クライアントは content_available と content_status を見て、次に呼ぶエンドポイントを判断してください。
機能の分離
| やりたいこと | 判断に使うフィールド / エンドポイント | 次のアクション |
|---|---|---|
| 文書メタデータを見つける | GET /v1/documents | document_id、content_status、reference_url を保存する |
| 本文検索する | POST /v1/search/documents | content_available=true の文書だけが対象 |
| 本文を取得する | content_status=ready、GET /v1/documents/{document_id}/toc | character_count を見て、必要な section_id だけ /content で取得する |
| 元ファイルを取得する | GET /v1/documents/{document_id}/originals | 一覧に含まれる original_id をファイル取得エンドポイントに渡す |
| ページ画像を取得する | image_available、GET /v1/documents/{document_id}/page-images | 一覧に含まれる page_number を画像取得エンドポイントに渡す |
| 外部発信元を確認する | reference_url | 外部サイトへの導線として表示する |
reference_url は外部発信元の確認用です。PDF / ZIP などの元ファイルは /originals で確認してください。
現行の対応範囲
主要市場上場企業に紐づく documents メタデータは、2002 年以降に企業公式サイトで公開された資料のメタデータを含みます。
| 対象 | 期間の目安 | 備考 |
|---|---|---|
| documents メタデータ | 2002-05-01 以降 | external_only や pending_release を含む |
| 本文検索・本文取得 | 2024-04-01 以降が中心 | content_status=ready の文書が対象 |
| 元ファイル取得 | 2024-04-01 以降が中心 | /originals に manifest がある文書が対象 |
| ページ画像取得 | 2025-06-16 以降が中心 | 主に適時開示 PDF 向け |
| news | 2026-04-21 以降 | 記事本文ではなく statement と references を返す |
この表は公開 API の実用上の目安です。対象範囲は継続的に増えます。正確なエンドポイント仕様は API Reference、プランごとの利用上限は Pricing を参照してください。実装では文書種別や日付だけで取得可否を推測せず、各レスポンスの content_status、image_available、/originals、/page-images を確認してください。
documents の種類
document_family | メタデータ | 本文検索・本文取得 | 備考 |
|---|---|---|---|
edinet_filing | 2024-04-01 以降 | 2024-04-01 以降の有価証券報告書が中心 | XBRL / PDF 由来の正規化本文と元ファイルを扱う |
timely_disclosure | 2021-11-12 以降 | 2025-06-16 以降が中心 | 決算短信、業績予想修正、中期経営計画など |
ir_material | 2002-05-01 以降 | v1 では対象外 | 企業公式サイトで公開された資料のメタデータ / 外部リンク。external_only |
ir_material は、決算説明資料、月次資料、説明会資料などを外部発信元で確認するためのメタデータです。v1 ではモモンガサーチ API から本文、元ファイル、ページ画像を配信しません。必要に応じて reference_url で外部発信元を確認してください。
最新開示と pending_release
適時開示では、上流データ提供条件や権利処理の都合により、開示直後に本文、検索 snippet、section、元ファイルを API で返せない場合があります。
その場合、文書メタデータは content_status=pending_release として返ることがあります。pending_release は一時状態です。retry_after_seconds が返る場合は、その値を目安に再試行してください。
開示から 24 時間が経過し、公開用 content の準備が完了すると、content_status=ready になり /toc、/content、/originals などを利用できるようになります。ただし、24 時間の経過だけで本文取得を保証するものではありません。必ず content_status を確認してください。
24 時間以内の適時開示では、published_at=null のまま、企業公式サイトから独立に確認できたメタデータと reference_url だけを返す場合があります。公式な公表時刻だけが必要な場合は published_at、発見・ページネーションの時間軸が必要な場合は timeline_at を使います。
external_only
external_only は、モモンガサーチ API では本文や元ファイルを配信せず、外部発信元への確認用 URL だけを提供する状態です。
主に企業公式サイト上の外部資料が該当します。これらは文書発見には有用ですが、発信元ごとに利用条件、再配信条件、ファイル配置の安定性が異なります。そのため v1 では、メタデータと reference_url の提供に限定し、全文検索・本文・元ファイル・ページ画像の配信とは分けています。
external_only は再試行待ちではありません。本文やファイルが必要な場合は reference_url から発信元を確認してください。
エンドポイントごとに対応範囲が違う理由
企業公表資料は、EDINET、TDNet、企業公式サイトなど複数の発信元にまたがります。発信元ごとにデータ形式、公開タイミング、再配信条件、権利処理、サイト構成の安定性が異なります。
モモンガサーチ API は、取得できない本文や元ファイルをクライアントが前提にしないよう、文書メタデータ、本文配信、元ファイル配信、ページ画像配信を分けています。取得可否は文書種別や日付から推測せず、API が返す content_status、content_available、image_available、/originals、/page-images で判断してください。
利用規約上のデータ利用範囲、第三者提供、再配信、派生データの扱いは 利用規約 を参照してください。このページでは、実装時に必要な取得可否と分岐だけを説明します。
実装チェックリスト
- 一覧・同期には
GET /v1/documentsとカーソルページネーションを使い、全文検索 API を全量取得に使わない。 content_available=falseの文書では/contentを呼ばず、content_statusを見る。/tocは 0-credit API だが、content_status=readyの文書だけで使う。pending_releaseはretry_after_secondsを尊重して再試行する。external_onlyは再試行せず、reference_urlを外部確認導線として扱う。- 元ファイルは
reference_urlから推測せず、GET /v1/documents/{document_id}/originalsの結果だけを取得対象にする。 - ページ画像は
page_countやページ番号から推測せず、GET /v1/documents/{document_id}/page-imagesの結果だけを取得する。 timeline_atを公式発表時刻として扱わない。公式時刻が必要な場合はpublished_atを使う。