瀏覽全部文件

公司篩選器 API 參考

依最新基本面的篩選條件查找公司,並讀取最多 10 家公司的財務項目

概覽

篩選器會在 Narwhal 持有的各申報登記機關範圍內,查找最新財務數字符合你所設條件的上市公司。你送出諸如淨利率高於 20% 之類的篩選條件,它就會回傳符合的公司,以及你要求的數字。每個請求都需要 Bearer 金鑰,REST 和 MCP 共用同一份額度餘額。

共有三條路由。第一條負責篩選。第二條列出篩選可用的所有欄位、運算子、幣別和登記機關,不收費。第三條一次請求就回傳你已知的最多 10 家公司的指定財務項目。公司以申報文件 API 的 ID 表示,例如 usa:0000320193。

每家公司依口徑各有一筆資料列:最新會計年度(annual)、最新季度(quarterly),或最近四個季度合計(ttm)。這些資料列每晚依申報文件重建,篩選條件清單中的 built_at 會說明重建時間。金額以公司自己的幣別計,不做換算,因此針對金額的篩選或排序需要 currency。每個金額還有一個帶後綴 _usd 的對應欄位,例如 revenue_usd,它不需要幣別。目前 _usd 的數字只會為以美元申報的公司填入,因此 _usd 篩選只會回傳這些公司。

篩選器建立在基本面資料之上。價格欄位在該公司的相關作業執行後,由每日收盤價填入,在此之前為空。公司未申報的數字不會出現在其資料列中,某個欄位沒有值的公司不會符合針對該欄位的篩選。

基礎網址: https://api.narwhalapi.com。 下列每條路由都是各自獨立的 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 個值。每個欄位接受的運算子見篩選條件清單,與欄位不符的篩選條件會回傳 400 invalid_query 並附上原因。文字值比對時不分大小寫。
  • limit 未設定時為 25,上限 100。沒有 order_by 時,公司依公司 ID 順序排列。order_by 接受數值欄位,order 未設為 asc 時為 desc。
  • 一頁可能以 next_cursor 結尾。把它作為 cursor 傳回,其他參數保持不變。來自另一個查詢的游標會得到 400 invalid_cursor。
  • fields 最多指定 106 個要回傳的數值欄位。未設定時,資料列包含你篩選或排序所用的欄位,沒有這些欄位時則包含營收、淨利和總資產。數字為十進位字串,公司沒有值的欄位會省略。
  • 如果之後的申報文件重編了某個數字,篩選器會顯示重編後的數值,與財務資料路由相同。
  • as_of 依過去某一天的狀態篩選公司,最早為 2010 年 1 月 31 日。資料列按月底保存,因此一份申報文件要從其提交之後的月底起才會顯示。只涵蓋目前仍上市的公司,最新數字的截止日早於該日超過 18 個月的公司會被排除。價格欄位不能與 as_of 一起使用,未來的日期會得到 400 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_cursor 分頁。價格取決於回傳的公司數量:每 10 家計一次呼叫,無條件進位。

每個篩選條件是一個物件,包含 field、operator(gt、gte、lt、lte、eq、ne 或 in)和 value。value 為數字或文字,in 時為清單,日期寫成 YYYY-MM-DD。

價格為頁面中每 10 家公司計一次呼叫,無條件進位,空頁不收費。請見上文的限制。

MCP:工具 filings_screen_companies。

參數

參數位置必填類型含義
basisbody否one of annual, quarterly, ttm篩選每家公司的哪一筆資料列:annual:最新會計年度。流量項目涵蓋整個年度,餘額項目為年度結束時的數字。quarterly:最新季度。流量項目只涵蓋該季度(未單獨提交的第四季為全年減去前三季),餘額項目為季度結束時的數字。成長率與一年前的同一季度比較。只按年提交的公司沒有季度資料列。ttm:最近四個季度合計(只按年提交,或季度不是連續四個的公司,則為會計年度本身);餘額項目為最後一個季度結束時的數字。成長率與一年前結束的四個季度比較。若有提供價格比率,則不論請求哪一筆資料列,都使用這個口徑。
filtersbody否物件陣列公司必須符合的條件,每個為 {field, operator, value}。最多 20 個。沒有篩選條件時,所有公司都符合。
currencybody否字串只包含以此幣別申報的公司。金額不做換算,因此針對金額或每股欄位的篩選或排序,需要在此指定一個幣別,或加一個 currency 的 eq 篩選條件。
fieldsbody否list of string要回傳的數值欄位。預設:用於篩選或排序的欄位。
order_bybody否字串一個數值欄位。預設:公司 ID。
orderbody否one of asc, descdesc 把 order_by 值最高的排在最前,asc 把最低的排在最前。預設為 desc。
langbody否one of en, originalen 在已知時回傳公司的英文名稱,original 回傳申報時的名稱。預設為 en。
as_ofbody否日期依這一天的狀態篩選公司:每家公司最新的資料列由截至當時已提交的申報文件建立,自 2010-01-31 起。資料列按月底保存,因此一份申報文件要從其提交之後的月底起才會顯示(絕不會更早)。只涵蓋目前仍上市的公司,最新數字的截止日早於該日超過 18 個月的公司會被排除。價格欄位(close、market_cap、價格比率與殖利率)不保存,不能與它一起使用。
limitbody否整數每頁的公司數,1 到 100。預設為 25。每頁依每 10 家公司計一次呼叫,無條件進位。
cursorbody否字串上一頁的 next_cursor,其他參數須與上一頁相同。

回應欄位

欄位類型傳送含義
companies物件陣列固定回傳本頁的公司,每家一筆資料列。空清單表示沒有符合的公司。
companies[].id字串固定回傳公司 ID,用於其他申報文件 API 路由。
companies[].name字串固定回傳公司名稱,當 lang 為 en 且已知英文名稱時為英文名稱。
companies[].ticker字串選填公司交易所用的股票代碼(如有)。
companies[].registryone 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_year整數選填該筆資料列的會計年度。
companies[].period_end日期選填該筆資料列期間的最後一天。
companies[].filed_on日期選填該筆資料列所依據的申報文件的提交日期。
next_cursor字串選填把它作為 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_get_screen_filters。

參數

此路由不接受任何參數。

回應欄位

欄位類型傳送含義
fields物件陣列固定回傳
fields[].field字串固定回傳欄位名稱,用於 filters、order_by 和 fields。
fields[].typeone of text, date, integer, amount, per_share, shares, percent, ratio, days, usd固定回傳欄位所含值的類型。
fields[].operatorslist of one of gt, gte, lt, lte, eq, ne, in固定回傳針對該欄位的篩選條件所接受的運算子。
fields[].unit字串選填值的單位(如有)。
fields[].description字串固定回傳該欄位是什麼。
bases物件陣列固定回傳
bases[].basisone of annual, quarterly, ttm固定回傳basis 的一個取值。
bases[].description字串固定回傳篩選每家公司的哪一筆資料列。
currencies物件陣列固定回傳公司申報所用的幣別,以及每個幣別對應的公司數量。
currencies[].value字串固定回傳幣別代碼。
currencies[].companies整數固定回傳以該幣別申報的公司數量。
registries物件陣列固定回傳
registries[].value字串固定回傳登記機關代碼。
registries[].companies整數固定回傳該登記機關持有的公司數量。
built_at日期時間選填篩選器資料表上次重建的時間。
max_filters整數選填一次篩選最多接受的篩選條件數。
max_limit整數選填一頁最多容納的公司數。
請求
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_found 中。每找到一家公司計一次呼叫。

period 未設定時為 annual。回應中,所請求期間的資料列以該名稱給出,最新的在前,ttm 資料列放在 ttm 下。

價格為每找到一家公司計一次呼叫,最多 10 家。一家也沒找到的請求免費。

MCP:工具 filings_search_line_items。

參數

參數位置必填類型含義
tickersbody是list of string公司 ID(usa:0000320193)、帶登記機關的股票代碼(usa:AAPL、jpn:7203),或不帶登記機關的美國股票代碼(AAPL)。
line_itemsbody是list of string標準項目名稱,與財務資料路由的 fields 相同。
periodbody否one of annual, semiannual, quarterly, ttmttm 是在每個季度結束時累計的最近四個季度合計(資產負債表項目取最後一個季度的數字;只按年提交的公司使用其會計年度)。其他期間與財務資料路由相同。
start_datebody否日期只包含在這一天或之後結束的期間。
end_datebody否日期只包含在這一天或之前結束的期間。
limitbody否整數每家公司的期間數,最新的在前。預設:1,給出日期時為日期範圍內的每個期間(最多 40 個)。

回應欄位

欄位類型傳送含義
results物件陣列固定回傳
results[].id字串固定回傳公司 ID。
results[].currency字串選填數字的幣別。
results[].basisone of consolidated, standalone選填數字是合併口徑還是個體口徑。
results[].from_fy整數選填各資料列回溯到的第一個會計年度。
results[].annual物件陣列選填年度資料列,最新的在前。當 period 為 annual 時傳回。
results[].annual[].fy整數固定回傳該筆資料列的會計年度。
results[].annual[].fq整數選填會計季度,用於季度資料列。
results[].annual[].fh整數選填會計半年度,用於半年度資料列。
results[].annual[].end日期固定回傳期間的最後一天。
results[].annual[].form字串選填提供該資料列所示大部分數值的申報文件的表格類型,例如 10-K。並列時以提交時間最近的為準。只統計你請求的欄位,因此在 line_items 不同的兩次請求中,form 可能不同。
results[].annual[].currency字串選填價格的幣別。
results[].annual[].derivedlist 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_items 不同的兩次請求中,form 可能不同。
results[].semiannual[].currency字串選填價格的幣別。
results[].semiannual[].derivedlist 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_items 不同的兩次請求中,form 可能不同。
results[].quarterly[].currency字串選填價格的幣別。
results[].quarterly[].derivedlist of string選填該資料列中由 Narwhal 計算得出、而非取自申報文件的項目。
results[].as_of日期選填數字所截至的日期,僅在該期間要求時才有。
results[].ttm物件陣列選填最近四個季度合計資料列,最新的在前。當 period 為 ttm 時傳回。
results[].ttm[].fy整數固定回傳該筆資料列的會計年度。
results[].ttm[].fq整數選填會計季度,用於季度資料列。
results[].ttm[].fh整數選填會計半年度,用於半年度資料列。
results[].ttm[].end日期固定回傳期間的最後一天。
results[].ttm[].form字串選填提供該資料列所示大部分數值的申報文件的表格類型,例如 10-K。並列時以提交時間最近的為準。只統計你請求的欄位,因此在 line_items 不同的兩次請求中,form 可能不同。
results[].ttm[].currency字串選填價格的幣別。
results[].ttm[].derivedlist of string選填該資料列中由 Narwhal 計算得出、而非取自申報文件的項目。
not_foundlist 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_id。查看 API 錯誤 處理:錯誤碼、額度與重試 了解格式與額度標頭。失敗的請求不計費。

代碼狀態含義
invalid_query400參數缺漏、未知、重複,或超出範圍。
invalid_cursor400此游標不是這個請求所回傳的,或來自不同的請求。
insufficient_credits402您的額度餘額不足以支付此請求的費用。
screener_unavailable503夜間篩選器資料表尚未建立。請稍後再試。此情況不收費。
company_data_unavailable503`as_of` 篩選未能及時讀取。請稍後再試。此情況不收費。

此頁面對你有幫助嗎?