公司筛选器 API 参考
按最新基本面的筛选条件查找公司,并读取最多 10 家公司的财务项目
概览
筛选器会在 Narwhal 持有的各披露文件登记机构范围内,查找最新财务数据满足你所设条件的上市公司。你发送诸如净利率高于 20% 之类的筛选条件,它就返回匹配的公司及你要求的数据。每个请求都需要 Bearer 密钥,REST 和 MCP 共用同一份额度余额。
共三个接口。第一个负责筛选。第二个列出筛选可用的所有字段、运算符、币种和登记机构,不收费。第三个一次请求就返回你已知的最多 10 家公司的指定财务项目。公司用披露文件 API 的 ID 表示,例如 usa:0000320193。
每家公司按口径各有一行:最新财年(annual)、最新季度(quarterly)或最近四个季度合计(ttm)。这些行每晚根据披露文件重建,筛选条件列表中的 built_ 会说明重建时间。金额按公司自己的币种计,不做换算,因此对金额的筛选或排序需要 currency。每个金额还有一个带后缀 _ 的对应字段,例如 revenue_,它不需要币种。目前 _ 数据只为以美元申报的公司填写,因此 _ 筛选只会返回这些公司。
筛选器建立在基本面数据之上。价格字段在该公司的相应任务运行后,由每日收盘价填入,在此之前为空。公司未披露的数据不会出现在它的行中,某个字段没有值的公司不会匹配针对该字段的筛选。
基础 URL: 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": []
}错误
错误使用通用的 problem 结构,并带有 request_。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。
| 代码 | 状态 | 含义 |
|---|---|---|
invalid_ | 400 | 参数缺失、未知、重复或超出范围。 |
invalid_ | 400 | 该游标不是本请求返回的,或来自另一个请求。 |
insufficient_ | 402 | 您的额度余额低于该请求的费用。 |
screener_ | 503 | 夜间筛选器表尚未构建。请稍后重试。此情况不收费。 |
company_ | 503 | `as_of` 筛选未能及时读取。请稍后重试。此情况不收费。 |
此页面对你有帮助吗?