企業スクリーナーAPIリファレンス
最新のファンダメンタルズに対するフィルターで企業を探し、最大10社の財務項目を読み取ります
概要
スクリーナーは、設定した条件を最新の財務数値が満たす上場企業を、Narwhalが保有する開示書類の登録機関をまたいで探します。純利益率が20パーセントを超えるといったフィルターを送ると、条件に合う企業と、指定した数値を返します。すべてのリクエストにBearerキーが必要で、RESTとMCPは1つのクレジット残高を共有します。
ルートは3つです。1つ目は絞り込みを行います。2つ目は、絞り込みで使えるフィールド、演算子、通貨、登録機関をすべて一覧にし、無料です。3つ目は、すでに分かっている最大10社について、選んだ財務項目を1回のリクエストで返します。企業は開示書類APIのID、たとえばusa:0000320193で指定します。
各企業には基準ごとに1行あります。最新の会計年度(annual)、最新の四半期(quarterly)、直近4四半期の合計(ttm)です。行は毎晩、開示書類から作り直され、いつ作り直されたかはフィルター一覧のbuilt_で分かります。金額は企業自身の通貨のままで換算されないため、金額に対するフィルターや並び替えにはcurrencyが必要です。各金額には、接尾辞_が付いた対になる項目もあります。たとえばrevenue_で、通貨の指定は不要です。現時点で_の数値が入るのは米ドルで報告する企業だけなので、_のフィルターはそれらの企業のみを返します。
スクリーナーは財務データを基にしています。価格のフィールドは、その企業についてその処理が実行されたあと、日次の終値から入り、それまでは空です。企業が報告していない数値は行から省かれ、あるフィールドに値がない企業は、そのフィールドへのフィルターに一致しません。
ベースURL: https:/。 以下の各ルートは、同じパラメータを持つ独立したMCPツールです。
1社の財務諸表は次にあります: 財務諸表API:開示書類リファレンス。
企業IDは次が返すものです: 開示書類 API 企業検索から返されます。
すべてのアカウントで利用できるもの
| 課金額 | すべてのアカウント |
|---|---|
| 絞り込み | 含まれます。返された企業10社ごとに1回の呼び出し(端数は切り上げ) |
| フィルター一覧 | 含まれます。無料 |
| 財務項目 | 含まれます。見つかった企業1社ごとに1回の呼び出し(最大10社) |
参照: 料金表 で、呼び出し1回の料金を確認できます。ルートに別の記載がない限り、リクエストはそのAPIの料金で課金されます。
- 絞り込みは、返されるページの企業数で課金されます。料金はCompanies料金の1,000回の呼び出しにつき$10、つまり1回$0.01で、企業10社ごとに1回、端数は切り上げです。1社から10社は1回($0.01)、11社から20社は2回($0.02)、100社が入った満杯のページは10回($0.10)です。何も一致しない絞り込みは無料で、すべてのエラーも無料です。
- 各ページはそのページの行数で課金されるため、ページを分けても1社あたりの料金は変わりません。10件のページと100件の1ページは、同じ企業なら同じ料金です。10の倍数でないページは切り上げになるので、
limitが1なら1社$0.01です。カーソルで結果全体を読むと、企業10社ごとに少なくとも1回の呼び出しがかかります。 - リクエストの料金は、レスポンスヘッダー
X-Narwhal-Costに、小数6桁のドルで入っています(23社のページなら0.030000)。X-Narwhal-Balanceは残高です。回答本体には料金のフィールドはありません。MCPでも同じ金額が残高から引かれ、呼び出しログに表示されます。何も一致しない絞り込みは0.000000です。 - 残高が1回の呼び出しに満たない場合は、実行前に402
insufficient_で拒否されます。ページ全体を支払えない場合は、実行後に拒否されます。どちらの場合も企業は返されず、課金もされません。支払いを減らすには、小さいcredits limitを送ってください。 - 絞り込みでは最大20個のフィルターを使えます。
in演算子は1個から50個の値を取ります。各フィールドが受け付ける演算子はフィルター一覧にあり、フィールドに合わないフィルターは理由つきの400invalid_です。テキストの値は大文字小文字を区別せずに照合されます。query limitは指定しなければ25で、最大100です。order_がない場合、企業は企業IDの順に並びます。by order_には数値フィールドを指定でき、by orderはascを指定しない限りdescです。- ページは
next_で終わることがあります。それを、ほかのパラメーターを同じにしてcursor cursorとして送り返します。別のクエリのカーソルは400invalid_です。cursor fieldsには、返したい数値フィールドを最大106個指定できます。指定しない場合、行にはフィルターや並び替えに使ったフィールドが入り、それがなければ売上、純利益、総資産が入ります。数値は小数文字列で、企業に値がないフィールドは省かれます。- 後の開示書類で数値が修正された場合、スクリーナーは修正後の値を表示します。財務ルートと同じです。
as_は、過去のある日の時点の企業で絞り込みます。2010年1月31日以降を指定できます。行は月末ごとに保存されるため、開示書類は提出後の最初の月末から反映されます。対象は現在上場している企業だけで、最新の数値の期末がその日の18か月より前の企業は除外されます。価格のフィールドはof as_と併用できず、未来の日付は400of invalid_です。query - 財務項目は、
tickersを最大10個、line_を最大20個指定でき、items limitは1社あたり最大40期間です。どの企業にも一致しないティッカーはnot_に一覧され、課金されません。同じ企業が2回指定された場合(found AAPLとusa:AAPL)は、1回だけ見つかり、1回だけ課金されます。プランの制限、保留された数値(妥当性チェックに通らず、どの回答にも含まれない数値)、撤回された開示書類の扱いは、財務ルートと同じです。
エンドポイント
Each route is marked GET or POST. A POST route takes a JSON body, and its parameters below are the fields of that body. Every route needs your key in the Authorization: Bearer ヘッダー。例はレスポンスの形を示すもので、ライブデータではありません。
ファンダメンタルズで企業を絞り込む
POST /v1/companies/screen
開示書類の登録機関をまたいで、上場企業を最新の会計年度で探します。条件は、フィルター一覧にあるフィールドに対するfiltersのリスト、任意の並び順、返すフィールドです。next_でページ送りします。料金は返された企業数で決まり、10社ごとに1回の呼び出し(端数は切り上げ)です。
各フィルターは、field、operator(gt、gte、lt、lte、eq、ne、inのいずれか)、valueを持つオブジェクトです。valueは数値またはテキストで、inではリスト、日付はYYYY-MM-DDで指定します。
料金はページ内の企業10社ごとに1回の呼び出しで、端数は切り上げ、空のページは無料です。上の制限を参照してください。
MCP: ツール filings_。
パラメータ
| パラメータ | 場所 | 必須 | 種別 | 意味 |
|---|---|---|---|---|
basis | body | いいえ | one of annual, quarterly, ttm | 各企業のどの行を絞り込み対象にするか。annual:最新の会計年度。フローはその年度の分、残高はその期末の値です。quarterly:最新の四半期。フローはその四半期だけの分(単独で提出されない第4四半期は、通期から第1四半期、第2四半期、第3四半期を引いたもの)、残高は期末の値です。成長率は1年前の同じ四半期との比較です。年次でしか提出しない企業には四半期の行がありません。ttm:直近4四半期の合計(年次でしか提出しない企業、または四半期が4つ連続していない企業では会計年度そのもの)。残高は最後の四半期末の値です。成長率は1年前に終わる4四半期との比較です。株価倍率は、提供されている場合、どの行を指定しても、この基準を使います。 |
filters | body | いいえ | オブジェクトの配列 | 企業が満たすべき条件で、それぞれ{field, operator, value}です。最大20個です。フィルターがなければ、すべての企業が一致します。 |
currency | body | いいえ | 文字列 | この通貨で報告する企業のみ。金額は換算されないため、金額または1株あたりのフィールドに対するフィルターや並び替えには、ここで1つの通貨を指定するか、currencyのeqフィルターが必要です。 |
fields | body | いいえ | list of string | 返す数値フィールド。デフォルトは、フィルターまたは並び替えに使ったもの。 |
order_ | body | いいえ | 文字列 | 数値フィールド。デフォルトは企業ID。 |
order | body | いいえ | one of asc, desc | descはorder_の値が最も高いものを先に、ascは最も低いものを先に並べます。デフォルトはdescです。 |
lang | body | いいえ | one of en, original | enは、分かっている場合は企業の英語名を返し、originalは提出されたままの名称を返します。デフォルトはenです。 |
as_ | body | いいえ | 日付 | この日の時点の企業で絞り込みます。各企業の最新の行を、その日までに提出された開示書類から作り、2010-01-31以降が対象です。行は月末ごとに保存されるため、開示書類は提出後の最初の月末から反映されます(それより前には反映されません)。対象は現在上場している企業だけで、最新の数値の期末がその日の18か月より前の企業は除外されます。価格のフィールド(close、market_、株価倍率、利回り)は保存されておらず、これと併用できません。 |
limit | body | いいえ | 整数 | ページに含める企業数で、1から100です。デフォルトは25です。ページは、企業10社ごとに1回の呼び出しで課金され、端数は切り上げです。 |
cursor | body | いいえ | 文字列 | 前のページの next_。ほかのパラメータは同じ値にします。 |
レスポンスフィールド
| フィールド | 種別 | 送信 | 意味 |
|---|---|---|---|
companies | オブジェクトの配列 | 常に | このページの企業で、1社につき1行です。空のリストは、何も一致しなかったことを意味します。 |
companies[].id | 文字列 | 常に | 企業ID。ほかの開示書類APIのルートで使います。 |
companies[].name | 文字列 | 常に | 企業名。langがenで、英語名が分かっている場合は英語名です。 |
companies[].ticker | 文字列 | 任意 | 企業が取引されているティッカー(ある場合)。 |
companies[].registry | one of usa, jpn, kor, gbr, twn, aut, bel, cyp, cze, dnk, est, esp, fin, fra, grc, hrv, hun, isl, ita, ltu, lux, lva, mlt, nld, nor, pol, prt, rou, swe, svn, svk | 常に | 企業が提出する登録機関。 |
companies[].country | 文字列 | 任意 | 企業の国。ISO 3166-1 alpha-3コードです。 |
companies[].isic | 文字列 | 任意 | 企業のISIC産業コード。 |
companies[].currency | 文字列 | 任意 | 企業が報告に使う通貨。 |
companies[].fiscal_ | 整数 | 任意 | その行の会計年度。 |
companies[].period_ | 日付 | 任意 | その行の期間の最終日。 |
companies[].filed_ | 日付 | 任意 | その行の元になった開示書類が提出された日。 |
next_ | 文字列 | 任意 | 次のページを読むには、これをcursorとして送り返します。最後のページでは省かれます。 |
curl -X POST -H "Authorization: Bearer $NARWHAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":[{"field":"net_margin","operator":"gt","value":20},{"field":"revenue","operator":"gt","value":50000000000}],"currency":"USD","order_by":"net_margin","fields":["net_margin","revenue"],"limit":3}' \
"https://api.narwhalapi.com/v1/companies/screen"{
"companies": [
{
"id": "usa:0000723125",
"name": "MICRON TECHNOLOGY INC",
"ticker": "MU",
"registry": "usa",
"country": "USA",
"isic": "2610",
"currency": "USD",
"fiscal_year": 2026,
"period_end": "2026-09-03",
"filed_on": "2026-10-09",
"revenue": "133188000000",
"net_margin": "63.7963"
},
{
"id": "usa:0001045810",
"name": "NVIDIA CORP",
"ticker": "NVDA",
"registry": "usa",
"country": "USA",
"isic": "2610",
"currency": "USD",
"fiscal_year": 2026,
"period_end": "2026-01-25",
"filed_on": "2026-02-25",
"revenue": "215938000000",
"net_margin": "55.6025"
},
{
"id": "usa:0000789019",
"name": "MICROSOFT CORP",
"ticker": "MSFT",
"registry": "usa",
"country": "USA",
"isic": "5820",
"currency": "USD",
"fiscal_year": 2026,
"period_end": "2026-06-30",
"filed_on": "2026-07-29",
"revenue": "331839000000",
"net_margin": "40.3054"
}
],
"next_cursor": "eyJpIjo3MjYsImtpbmQiOiJzY3JlZW4iLCJvIjoiNDAuMzA1NCIsInEiOiJlMWFjYzEzMjM1NTE5OGNmIiwidiI6MX0.z_-8qfS3wrPvM52pvfH2QEc6Z8LcktMIJH8zF5yjvmo"
}スクリーナーのフィールドと制限を一覧にする
GET /v1/companies/screen/filters
絞り込みでフィルター、並び替え、返却ができるすべてのフィールドを、型、単位、演算子とともに返します。あわせて、基準、スクリーナーが保有する通貨と登録機関、そして制限も返します。無料です。このルートは課金されません。
回答はすべてのアカウントで同じです。通貨と登録機関ごとの企業数は、最新の再構築時点のものです。
MCP: ツール filings_。
パラメータ
このルートにパラメーターはありません。
レスポンスフィールド
| フィールド | 種別 | 送信 | 意味 |
|---|---|---|---|
fields | オブジェクトの配列 | 常に | |
fields[].field | 文字列 | 常に | フィールド名。filters、order_、fieldsで使うものです。 |
fields[].type | one of text, date, integer, amount, per_share, shares, percent, ratio, days, usd | 常に | フィールドが保持する値の種類。 |
fields[].operators | list of one of gt, gte, lt, lte, eq, ne, in | 常に | このフィールドに対するフィルターが受け付ける演算子。 |
fields[].unit | 文字列 | 任意 | 値の単位(ある場合)。 |
fields[].description | 文字列 | 常に | フィールドの内容。 |
bases | オブジェクトの配列 | 常に | |
bases[].basis | one of annual, quarterly, ttm | 常に | basisに指定できる値。 |
bases[].description | 文字列 | 常に | 各企業のどの行を絞り込み対象にするか。 |
currencies | オブジェクトの配列 | 常に | 企業が報告に使う通貨と、それぞれの企業数。 |
currencies[].value | 文字列 | 常に | 通貨コード。 |
currencies[].companies | 整数 | 常に | その通貨で報告する企業の数。 |
registries | オブジェクトの配列 | 常に | |
registries[].value | 文字列 | 常に | 登録機関コード。 |
registries[].companies | 整数 | 常に | その登録機関が保有する企業の数。 |
built_ | 日時 | 任意 | スクリーナーのテーブルが最後に再構築された日時。 |
max_ | 整数 | 任意 | 1回の絞り込みで使えるフィルターの最大数。 |
max_ | 整数 | 任意 | 1ページに含まれる企業の最大数。 |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/screen/filters"{ "fields": [ { "field": "registry", "type": "text", "operators": [ "eq", "ne", "in" ], "description": "Registry that holds the company (usa, jpn, kor, ...)." }, { "field": "revenue", "type": "amount", "operators": [ "gt", "gte", "lt", "lte", "eq", "ne", "in" ], "unit": "currency", "description": "Revenue in `currency`, for the period of the row (see `basis`)." }, { "field": "net_margin", "type": "percent", "operators": [ "gt", "gte", "lt", "lte", "eq", "ne", "in" ], "unit": "percent", "description": "Net income over revenue (revenue above zero)." }, { "field": "revenue_usd", "type": "usd", "operators": [ "gt", "gte", "lt", "lte", "eq", "ne", "in" ], "unit": "USD", "description": "revenue in US dollars: the figure times `usd_rate_avg` (the period's average rate). Empty where there is no rate. Today the `_usd` figures are filled only for companies that report in US dollars, so a `_usd` filter returns only those companies." } ], "bases": [ { "basis": "annual", "description": "The newest fiscal year. Flows cover the year; balances are at its end." }, { "basis": "quarterly", "description": "The newest quarter. Flows cover that quarter alone (a fourth quarter that is not filed on its own is the year minus the first three); balances are at its end. Growth is against the same quarter a year before. A company that files only annually has no quarterly row." }, { "basis": "ttm", "description": "The last four quarters added up (the fiscal year itself for a company that files only annually or whose quarters are not four in a row); balances are at the end of the last quarter. Growth is against the four quarters ending a year before. Price ratios, where offered, use this basis whatever row is asked for." } ], "currencies": [ { "value": "USD", "companies": 5408 }, { "value": "JPY", "companies": 3804 }, { "value": "KRW", "companies": 2628 } ], "registries": [ { "value": "usa", "companies": 5520 }, { "value": "jpn", "companies": 3784 }, { "value": "kor", "companies": 2637 } ], "built_at": "2026-11-16T04:18:58.438922Z", "max_filters": 20, "max_limit": 100 }最大10社の選択した財務項目を取得
POST /v1/companies/line-items
最大10個のtickersについて、選択した財務項目を1回のリクエストで返します。各企業の期間が新しい順に並びます。どの企業にも一致しないティッカーはnot_に一覧されます。見つかった企業1社ごとに1回の呼び出しです。
periodは指定しなければannualです。回答には、指定した期間の行がその名前で新しい順に入り、ttmの行はttmに入ります。
料金は、見つかった企業1社ごとに1回の呼び出しで、最大10社です。1社も見つからないリクエストは無料です。
MCP: ツール filings_。
パラメータ
| パラメータ | 場所 | 必須 | 種別 | 意味 |
|---|---|---|---|---|
tickers | body | はい | list of string | 企業ID(usa:0000320193)、登録機関付きのティッカー(usa:AAPL、jpn:7203)、または登録機関なしの米国ティッカー(AAPL)。 |
line_ | body | はい | list of string | 標準項目名。財務ルートのfieldsと同じです。 |
period | body | いいえ | one of annual, semiannual, quarterly, ttm | ttmは、各四半期末時点での直近4四半期の合計です(貸借対照表の項目は最後の四半期の値で、年次でしか提出しない企業では会計年度が使われます)。ほかの期間は財務ルートと同じです。 |
start_ | body | いいえ | 日付 | この日以降に終わる期間のみ。 |
end_ | body | いいえ | 日付 | この日以前に終わる期間のみ。 |
limit | body | いいえ | 整数 | 企業ごとの期間数で、新しい順です。デフォルトは1ですが、日付を指定した場合は日付範囲内のすべての期間(最大40)です。 |
レスポンスフィールド
| フィールド | 種別 | 送信 | 意味 |
|---|---|---|---|
results | オブジェクトの配列 | 常に | |
results[].id | 文字列 | 常に | 企業ID。 |
results[].currency | 文字列 | 任意 | 数値の通貨。 |
results[].basis | one of consolidated, standalone | 任意 | 数値が連結か単体か。 |
results[].from_ | 整数 | 任意 | 行がさかのぼる最初の会計年度。 |
results[].annual | オブジェクトの配列 | 任意 | 年次の行で、新しい順です。periodがannualのときに返されます。 |
results[].annual[].fy | 整数 | 常に | その行の会計年度。 |
results[].annual[].fq | 整数 | 任意 | 会計四半期。四半期の行の場合。 |
results[].annual[].fh | 整数 | 任意 | 会計上の半期。半期の行の場合。 |
results[].annual[].end | 日付 | 常に | 期間の最終日。 |
results[].annual[].form | 文字列 | 任意 | 行に表示される値の大半を提供する開示書類のフォーム。例:10-K。同数の場合は、最近提出されたものが優先されます。指定した項目だけが数えられるため、line_が異なる2つのリクエストではformが異なることがあります。 |
results[].annual[].currency | 文字列 | 任意 | 価格の通貨。 |
results[].annual[].derived | list of string | 任意 | 行の項目のうち、開示書類から取ったのではなくNarwhalが算出したもの。 |
results[].semiannual | オブジェクトの配列 | 任意 | 半期の行で、新しい順です。periodがsemiannualのときに返されます。 |
results[].semiannual[].fy | 整数 | 常に | その行の会計年度。 |
results[].semiannual[].fq | 整数 | 任意 | 会計四半期。四半期の行の場合。 |
results[].semiannual[].fh | 整数 | 任意 | 会計上の半期。半期の行の場合。 |
results[].semiannual[].end | 日付 | 常に | 期間の最終日。 |
results[].semiannual[].form | 文字列 | 任意 | 行に表示される値の大半を提供する開示書類のフォーム。例:10-K。同数の場合は、最近提出されたものが優先されます。指定した項目だけが数えられるため、line_が異なる2つのリクエストではformが異なることがあります。 |
results[].semiannual[].currency | 文字列 | 任意 | 価格の通貨。 |
results[].semiannual[].derived | list of string | 任意 | 行の項目のうち、開示書類から取ったのではなくNarwhalが算出したもの。 |
results[].quarterly | オブジェクトの配列 | 任意 | 四半期の行で、新しい順です。periodがquarterlyのときに返されます。 |
results[].quarterly[].fy | 整数 | 常に | その行の会計年度。 |
results[].quarterly[].fq | 整数 | 任意 | 会計四半期。四半期の行の場合。 |
results[].quarterly[].fh | 整数 | 任意 | 会計上の半期。半期の行の場合。 |
results[].quarterly[].end | 日付 | 常に | 期間の最終日。 |
results[].quarterly[].form | 文字列 | 任意 | 行に表示される値の大半を提供する開示書類のフォーム。例:10-K。同数の場合は、最近提出されたものが優先されます。指定した項目だけが数えられるため、line_が異なる2つのリクエストではformが異なることがあります。 |
results[].quarterly[].currency | 文字列 | 任意 | 価格の通貨。 |
results[].quarterly[].derived | list of string | 任意 | 行の項目のうち、開示書類から取ったのではなくNarwhalが算出したもの。 |
results[].as_ | 日付 | 任意 | 数値の基準日。期間が基準日を求める場合のみ。 |
results[].ttm | オブジェクトの配列 | 任意 | 直近4四半期の合計の行で、新しい順です。periodがttmのときに返されます。 |
results[].ttm[].fy | 整数 | 常に | その行の会計年度。 |
results[].ttm[].fq | 整数 | 任意 | 会計四半期。四半期の行の場合。 |
results[].ttm[].fh | 整数 | 任意 | 会計上の半期。半期の行の場合。 |
results[].ttm[].end | 日付 | 常に | 期間の最終日。 |
results[].ttm[].form | 文字列 | 任意 | 行に表示される値の大半を提供する開示書類のフォーム。例:10-K。同数の場合は、最近提出されたものが優先されます。指定した項目だけが数えられるため、line_が異なる2つのリクエストではformが異なることがあります。 |
results[].ttm[].currency | 文字列 | 任意 | 価格の通貨。 |
results[].ttm[].derived | list of string | 任意 | 行の項目のうち、開示書類から取ったのではなくNarwhalが算出したもの。 |
not_ | list of string | 任意 | どの企業にも一致しないティッカーまたはID。 |
curl -X POST -H "Authorization: Bearer $NARWHAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tickers":["AAPL","MSFT"],"line_items":["revenue","net_income"],"limit":1}' \
"https://api.narwhalapi.com/v1/companies/line-items"{
"results": [
{
"id": "usa:0000320193",
"currency": "USD",
"annual": [
{
"fy": 2026,
"end": "2026-09-26",
"form": "10-K",
"derived": [],
"revenue": "478834000000",
"net_income": "132175000000"
}
],
"as_of": "2026-11-03"
},
{
"id": "usa:0000789019",
"currency": "USD",
"annual": [
{
"fy": 2026,
"end": "2026-06-30",
"form": "10-K",
"derived": [],
"revenue": "331839000000",
"net_income": "133749000000"
}
],
"as_of": "2026-07-29"
}
],
"not_found": []
}エラー
エラーは共通の problem 形式で返され、次のコードを含みます: request_。参照: APIエラーとクレジット で形式とクレジットヘッダーを確認できます。失敗したリクエストには課金されません。
| コード | ステータス | 意味 |
|---|---|---|
invalid_ | 400 | パラメータが欠けている、未知である、重複している、または範囲外です。 |
invalid_ | 400 | このカーソルは、このリクエストが返したものではないか、別のリクエストのものです。 |
insufficient_ | 402 | クレジット残高が、リクエストの費用に足りません。 |
screener_ | 503 | 夜間のスクリーナーテーブルがまだ構築されていません。後でもう一度お試しください。これは課金されません。 |
company_ | 503 | `as_of`での絞り込みが時間内に読み取れませんでした。しばらくしてからもう一度お試しください。これは課金されません。 |
このページは役に立ちましたか?