エンドポイント
エンドポイントは、credits を消費しない 0-credit API と、credits を消費する credit API に分かれます。
基本の流れは、0-credit API で候補・取得可否・取得単位を確認し、必要な本文・画像・元ファイルだけ credit API で取得する形です。詳細なリクエスト / レスポンススキーマは API Reference を参照してください。
0-credit API
0-credit API は、文書を見つけて取得可否を判断するための API です。credits は消費しません。news は根拠付き statement が本体なので、一覧取得も credit API です。
| Endpoint | 用途 | 主な注意点 |
|---|---|---|
GET /v1/issuers/search | 企業名・証券コードから issuer を検索 | 企業名の揺れを吸収する入口 |
GET /v1/documents | 文書一覧を取得 | security_codes なしで市場全体を一覧する場合は timeline_since が必須 |
GET /v1/documents/{document_id} | 文書メタデータを取得 | 本文取得可否は content_status を見る |
GET /v1/documents/{document_id}/toc | 本文取得に使えるセクション一覧を取得 | content_status=ready の文書だけ対象。対象外は 409 content_not_available |
GET /v1/documents/{document_id}/page-images | 取得可能なページ画像を列挙 | ここに含まれる page_number だけ画像取得できる |
GET /v1/documents/{document_id}/originals | 取得可能な元ファイルを列挙 | ここに含まれる original_id だけファイル取得できる |
配列 query parameter は ?security_codes=8058&security_codes=7203 のように同名キーを繰り返します。カンマ区切りはサポートしません。
GET /v1/documents は security_codes、document_types、document_families、timeline_since / timeline_until で絞り込めます。security_codes なしで市場全体を一覧する場合は timeline_since が必須です。document_families は edinet_filing、timely_disclosure、ir_material を指定できます。
0 credits は無制限を意味しません。すべての API は認証とリクエスト上限の対象です。プランごとの具体的な利用上限は Pricing を参照してください。
credit API
credit API は、根拠付き news、文書本文や news の検索、本文・画像・元ファイル取得に使います。成功した 2xx レスポンスだけが credits 消費対象です。
| エンドポイント | 用途 | credits |
|---|---|---|
GET /v1/news | references[] 付き news 一覧を取得 | 1 request = 1 credit |
POST /v1/search/documents | 文書本文をキーワード検索 / 意味検索 | 1 request = 1 credit |
POST /v1/search/news | news をキーワード検索 / 意味検索 | 1 request = 1 credit |
GET /v1/documents/{document_id}/content | 文書本文または指定セクションを取得 | 返す本文量により 2 / 4 / 8 credits |
GET /v1/documents/{document_id}/pages/{page_number}/image | ページ画像を取得 | 1 page = 1 credit |
GET /v1/documents/{document_id}/originals/{original_id} | PDF / ZIP などの元ファイルを取得 | 1 file = 8 credits |
GET /v1/news は security_codes、timeline_since / timeline_until、macro_tags で絞り込めます。security_codes / macro_tags / timeline_since のいずれかが必須です。macro_tags を複数指定すると、いずれかのタグを含む news を返します。
POST /v1/search/documents の document_families は edinet_filing と timely_disclosure だけを受け付けます。ir_material はメタデータ一覧には出ますが、v1 の本文検索対象外です。match_type の既定値は semantic です。短い観点語で探す場合は match_type: "lexical" を明示してください。
エンドポイントごとの実用 coverage と鮮度は データ対応範囲 を参照してください。
POST /v1/search/news は security_codes、timeline_since / timeline_until、macro_tags を検索条件にできます。macro_tags は一覧 API と同じ OR 条件で、public v1 の 7 分類だけを受け付けます。
ページ画像は全ページにあるとは限りません。image_available=true の文書でも、まず GET /v1/documents/{document_id}/page-images で取得可能ページを確認してください。
元ファイルも同様に、まず GET /v1/documents/{document_id}/originals で取得可能な original_id、media type、ファイル名を確認してからファイル取得エンドポイントを呼びます。
現行 v1 では documents と news の横断検索 API はありません。文書本文は /search/documents、更新情報は /search/news を呼び分けてください。
エンドポイント / リクエスト / レスポンススキーマの詳細は API Reference を参照してください。API Reference は momonga-search-api の OpenAPI から生成しています。