公司篩選器 API 參考
依最新基本面的篩選條件查找公司,並讀取最多 10 家公司的財務項目
概覽
篩選器會在 Narwhal 持有的各申報登記機關範圍內,查找最新財務數字符合你所設條件的上市公司。你送出諸如淨利率高於 20% 之類的篩選條件,它就會回傳符合的公司,以及你要求的數字。每個請求都需要 Bearer 金鑰,REST 和 MCP 共用同一份額度餘額。
共有三條路由。第一條負責篩選。第二條列出篩選可用的所有欄位、運算子、幣別和登記機關,不收費。第三條一次請求就回傳你已知的最多 10 家公司的指定財務項目。公司以申報文件 API 的 ID 表示,例如 usa:0000320193。
每家公司依口徑各有一筆資料列:最新會計年度(annual)、最新季度(quarterly),或最近四個季度合計(ttm)。這些資料列每晚依申報文件重建,篩選條件清單中的 built_ 會說明重建時間。金額以公司自己的幣別計,不做換算,因此針對金額的篩選或排序需要 currency。每個金額還有一個帶後綴 _ 的對應欄位,例如 revenue_,它不需要幣別。目前 _ 的數字只會為以美元申報的公司填入,因此 _ 篩選只會回傳這些公司。
篩選器建立在基本面資料之上。價格欄位在該公司的相關作業執行後,由每日收盤價填入,在此之前為空。公司未申報的數字不會出現在其資料列中,某個欄位沒有值的公司不會符合針對該欄位的篩選。
基礎網址: https:/。 下列每條路由都是各自獨立的 MCP 工具,參數相同。
一家公司的財務報表請見 財報 API 參考文件。
公司 ID 即為 申報文件 API 公司搜尋所回傳的 ID。
每個帳戶都能取得的內容
| 費用 | 所有帳戶 |
|---|---|
| 篩選 | 已包含。每回傳 10 家公司計一次呼叫,無條件進位 |
| 篩選條件清單 | 已包含。免費 |
| 財務項目 | 已包含。每找到一家公司計一次呼叫,最多 10 家 |
查看 定價 說明每次呼叫的費用。除非路由另有說明,請求依其所屬 API 的價格計費。
- 篩選依所回傳頁面中的公司數量計費,依 Companies 價格每 1,000 次呼叫 $10,也就是每次呼叫 $0.01:每 10 家公司計一次呼叫,無條件進位。1 到 10 家公司為 1 次呼叫($0.01),11 到 20 家為 2 次呼叫($0.02),滿頁 100 家為 10 次呼叫($0.10)。沒有符合結果的篩選免費,所有錯誤也免費。
- 每一頁依其自身的資料列數計費,因此分頁不會改變每家公司的價格。對同樣的公司,每頁 10 家與一頁 100 家的費用相同。不是 10 的倍數的頁面會無條件進位,所以
limit為 1 時每家公司 $0.01。用游標讀取整個結果,每 10 家公司一律至少計一次呼叫。 - 請求的費用在
X-Narwhal-Cost回應標頭中,以美元表示,取到小數點後六位(23 家公司的一頁顯示0.030000),X-Narwhal-Balance是剩餘餘額。回應本身沒有費用欄位。透過 MCP 時,同樣的金額會從餘額扣除,並顯示在呼叫記錄中。沒有符合結果的篩選顯示0.000000。 - 餘額不足一次呼叫時,請求在執行前會被拒絕並回傳 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 - 財務項目最多接受 10 個
tickers和 20 個line_,items limit為每家公司最多 40 個期間。與任何公司都不符的股票代碼會列在not_中,不收費;同一家公司被指定兩次(found AAPL和usa:AAPL)時只會找到一次,也只計費一次。方案限制、暫緩提供的數字(未通過合理性檢查、不會出現在任何回應中的數字)與已撤回的申報文件,處理方式與財務資料路由相同。
端點
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 家計一次呼叫,無條件進位。
每個篩選條件是一個物件,包含 field、operator(gt、gte、lt、lte、eq、ne 或 in)和 value。value 為數字或文字,in 時為清單,日期寫成 YYYY-MM-DD。
價格為頁面中每 10 家公司計一次呼叫,無條件進位,空頁不收費。請見上文的限制。
MCP:工具 filings_。
參數
| 參數 | 位置 | 必填 | 類型 | 含義 |
|---|---|---|---|---|
basis | body | 否 | one of annual, quarterly, ttm | 篩選每家公司的哪一筆資料列:annual:最新會計年度。流量項目涵蓋整個年度,餘額項目為年度結束時的數字。quarterly:最新季度。流量項目只涵蓋該季度(未單獨提交的第四季為全年減去前三季),餘額項目為季度結束時的數字。成長率與一年前的同一季度比較。只按年提交的公司沒有季度資料列。ttm:最近四個季度合計(只按年提交,或季度不是連續四個的公司,則為會計年度本身);餘額項目為最後一個季度結束時的數字。成長率與一年前結束的四個季度比較。若有提供價格比率,則不論請求哪一筆資料列,都使用這個口徑。 |
filters | body | 否 | 物件陣列 | 公司必須符合的條件,每個為 {field, operator, value}。最多 20 個。沒有篩選條件時,所有公司都符合。 |
currency | body | 否 | 字串 | 只包含以此幣別申報的公司。金額不做換算,因此針對金額或每股欄位的篩選或排序,需要在此指定一個幣別,或加一個 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 家公司計一次呼叫,無條件進位。 |
cursor | body | 否 | 字串 | 上一頁的 next_,其他參數須與上一頁相同。 |
回應欄位
| 欄位 | 類型 | 傳送 | 含義 |
|---|---|---|---|
companies | 物件陣列 | 固定回傳 | 本頁的公司,每家一筆資料列。空清單表示沒有符合的公司。 |
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_ | 整數 | 選填 | 一次篩選最多接受的篩選條件數。 |
max_ | 整數 | 選填 | 一頁最多容納的公司數。 |
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 的指定財務項目:每家公司的各期間,最新的在前。與任何公司都不符的股票代碼會列在 not_ 中。每找到一家公司計一次呼叫。
period 未設定時為 annual。回應中,所請求期間的資料列以該名稱給出,最新的在前,ttm 資料列放在 ttm 下。
價格為每找到一家公司計一次呼叫,最多 10 家。一家也沒找到的請求免費。
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 是在每個季度結束時累計的最近四個季度合計(資產負債表項目取最後一個季度的數字;只按年提交的公司使用其會計年度)。其他期間與財務資料路由相同。 |
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_ 不同的兩次請求中,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_ 不同的兩次請求中,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_ 不同的兩次請求中,form 可能不同。 |
results[].quarterly[].currency | 字串 | 選填 | 價格的幣別。 |
results[].quarterly[].derived | list of string | 選填 | 該資料列中由 Narwhal 計算得出、而非取自申報文件的項目。 |
results[].as_ | 日期 | 選填 | 數字所截至的日期,僅在該期間要求時才有。 |
results[].ttm | 物件陣列 | 選填 | 最近四個季度合計資料列,最新的在前。當 period 為 ttm 時傳回。 |
results[].ttm[].fy | 整數 | 固定回傳 | 該筆資料列的會計年度。 |
results[].ttm[].fq | 整數 | 選填 | 會計季度,用於季度資料列。 |
results[].ttm[].fh | 整數 | 選填 | 會計半年度,用於半年度資料列。 |
results[].ttm[].end | 日期 | 固定回傳 | 期間的最後一天。 |
results[].ttm[].form | 字串 | 選填 | 提供該資料列所示大部分數值的申報文件的表格類型,例如 10-K。並列時以提交時間最近的為準。只統計你請求的欄位,因此在 line_ 不同的兩次請求中,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": []
}錯誤
錯誤使用共用的問題格式,並包含 request_。查看 API 錯誤 處理:錯誤碼、額度與重試 了解格式與額度標頭。失敗的請求不計費。
| 代碼 | 狀態 | 含義 |
|---|---|---|
invalid_ | 400 | 參數缺漏、未知、重複,或超出範圍。 |
invalid_ | 400 | 此游標不是這個請求所回傳的,或來自不同的請求。 |
insufficient_ | 402 | 您的額度餘額不足以支付此請求的費用。 |
screener_ | 503 | 夜間篩選器資料表尚未建立。請稍後再試。此情況不收費。 |
company_ | 503 | `as_of` 篩選未能及時讀取。請稍後再試。此情況不收費。 |
此頁面對你有幫助嗎?