申报文件文本与分部 API 参考
美国申报文件按项目划分的文本,以及分部、产品和地区数据
概览
申报文件文本返回美国公司在 10-K、10-Q、20-F 或 8-K 中所写的内容,并按项目标题切分,例如 Item 1A 风险因素或 Item 7 管理层讨论。分部数据把公司按分部、产品或地区拆分的数字加到其财务报表中。每个请求都需要 Bearer 密钥,REST 和 MCP 共用一份额度余额。
共有四个接口。其中两个返回一份申报文件的文本:一个按申报文件 id,一个按公司、表格和财年。一个列出每种表格有哪些项目。第四个是财务接口上的 segments=true,接口名称和价格都不变。公司用其 Filings API 的 id 指定,例如 usa:0000320193;申报文件用公司 id、一个冒号和 SEC 受理编号指定。
历史数据可回溯五年。文本尚未读取的申报文件返回 404 sections_;某一期间自身的报告尚未为分部数据读取时,该期间会列在 segments_ 中。
文本接口支持美国、日本和韩国。美国的申报文件是 10-K、10-Q、20-F 或 8-K。日本的申报文件是 YUHO、HANKI、SHIHANKI 或 RINJI,韩国的是 사업보고서、반기보고서 或 분기보고서。属于公司所在国以外国家的表格返回 400 invalid_。其他任何国家的公司返回 404 not_。文本尚未读取的日本或韩国申报文件返回 404 sections_。分部数据只适用于美国公司。
基础 URL: https:/。 下面每个路由都是一个独立的 MCP 工具,参数相同。
各财务报表的行见 财报 API 参考。
公司 id 与 披露文件 API 公司搜索返回的 id 相同。
每个账户可获得的内容
| 查看 | 所有账户 |
|---|---|
| 申报文件文本,两个接口 | 已包含 |
| 项目列表 | 已包含,免费 |
| 财务数据中的分部 | 已包含 |
查看 价格 了解每次调用的费用。请求按其所属 API 的价格计费,除非某个路由另有说明。
- 按 Companies 价格计费,每 1,000 次调用 $10。每个成功的文本响应计一次调用,不论项目、大小或格式。按公司查询的 8-K 为找到某个项目最多会读取最新的 10 份 8-K,仍然计一次调用。没有内容的响应免费;在文本接口上什么都没找到会返回 404,同样免费。项目列表免费。错误不计费。
segments=true不增加调用,也不增加价格。带上它的财务数据与不带时一样计一次调用。有财务数据行的响应按一次调用计费,不论segments有行、为空还是被省略。- 文本就是申报文件本身,按其项目标题切分。不会改写或概括。无法区分项目的申报文件返回 404
sections_,绝不返回部分文本。unavailable - 10-Q 在 Part I 有一个 Item 1,在 Part II 还有另一个 Item 1。不带
part时,item=1会同时返回两者。 - 不带
item的 8-K 还会以exhibits返回其附件的文本。附件文本被截断时,truncated为 true。 - 分部行给出该期间自身报告中所申报的数字:
value和它所在的filing_。如果之后的申报文件改变了这个数字,id restated会给出之后的数字及其来源申报文件。version=first_只返回最初申报的数字。reported restated_行没有only value和filing_,因为没有保存最初申报的数字。原因是该期间的报告中没有这个成员(之后的申报文件把该期间重新切分成了其他成员),或者该报告尚未读取,此时id restated是之后某份申报文件的数字,甚至可能根本不是重述。segments_按从新到旧列出期末日期,这些期间自身的报告尚未为分部数据读取。它们缺少最初申报的数字,这与没有申报不是一回事,它们的行都是unread restated_。没有读取过任何期间且之后的申报文件也没有数字时,only segments会被省略。member和label是公司对分部、产品或地区自己的说法,不会在公司之间做匹配。concept是公司使用的标签,因此同一measure的两个数字,例如含分部间销售和不含分部间销售的收入,会各自独立。percent_是该数字占公司合并数字的百分比,合并数字取自of_ total filing_所指申报文件中同一概念和期间,保留两位小数。成员相加不一定等于 100,因为申报人会加入小计和合并成员。如果该申报文件没有印出该概念和期间的合并数字,则省略。id - 分部数字以
currency的整单位表示。某一日期的数字,例如资产或商誉,没有start。
端点
每个路由都是 GET 请求,并需要在以下请求头中携带你的密钥: Authorization: Bearer 标头。示例仅展示响应的结构,并非实时数据。
按项目获取申报文件的文本
GET /v1/filings/{filing_id}/sections
一份申报文件的文本,按项目标题切分:全部项目,或用 item 取一个项目。可以是美国的 10-K、10-Q、20-F 或 8-K,也可以是日本或韩国的报告。无法区分项目的申报文件返回 404 sections_,绝不返回部分文本。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
filing_ | 路径参数 | 是 | 字符串 | 申报文件 id:公司 id、一个冒号和 SEC 受理编号,例如 usa:0000320193:0000320193-26-000026。Filings API 会列出它们。 |
item | 查询参数 | 否 | 字符串 | 按编号指定的一个项目,例如 1A 或 7。8-K 的项目形如 2.02。省略则返回全部项目。申报文件没有的项目返回 404 item_。 |
part | 查询参数 | 否 | 字符串 | 部分(I 到 IV)。10-Q 在 Part I 有一个 Item 1,在 Part II 还有另一个 Item 1;不带 part 时,item 会同时返回两者。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 申报文件 id。在财务数据中是公司 id。 |
form | 字符串 | 总是 | 申报文件的表格,例如 10-K。 |
sections | 对象数组 | 总是 | 申报文件的项目,按申报文件中的顺序排列。 |
sections[].item | 字符串 | 总是 | 项目编号,例如 1A,8-K 上是 2.02。 |
sections[].title | 字符串 | 总是 | 项目的标题,例如 Risk Factors。 |
sections[].text | 字符串 | 总是 | 项目的文本,与申报时一致。 |
sections[].part | 字符串 | 可选 | 项目所在的部分,I 到 IV。表格没有部分时省略。 |
exhibits | 对象数组 | 可选 | 8-K 的附件文件,以文本形式给出。省略 item 时发送。 |
exhibits[].type | 字符串 | 总是 | 附件类型,例如 EX-99.1。 |
exhibits[].name | 字符串 | 总是 | 附件的文件名。 |
exhibits[].text | 字符串 | 总是 | 附件的文本。 |
exhibits[].truncated | 布尔值 | 可选 | 文本被截断时为 true。 |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-26-000026/sections?item=1A"{
"id": "usa:0000320193:0000320193-26-000026",
"form": "10-K",
"sections": [
{
"item": "1A",
"title": "Risk Factors",
"text": "The following summarizes factors that could have a material adverse effect on the Company’s business, reputation, results of operations, financial condition and…",
"part": "I"
}
]
}按表格和年份获取公司的申报文件文本
GET /v1/companies/{company_id}/sections
与申报文件接口相同的文本,通过公司、表格和财年查找,因此不需要申报文件 id。不带 year 时是该表格最新的申报文件。对于带 item 的 8-K,是公司最近 10 份 8-K 中含有该项目的最新一份。
用 quarter 配合 form=10-Q 选择季度。与任何其他表格一起使用都会返回 400 invalid_。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
company_ | 路径参数 | 是 | 字符串 | 公司 id,例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。 |
form | 查询参数 | 是 | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | 表格,按公司所在国家的叫法:美国是 10-K、10-Q、20-F 或 8-K;日本是 YUHO、HANKI、SHIHANKI 或 RINJI;韩国是 사업보고서、반기보고서 或 분기보고서。其他任何值返回 400 invalid_。 |
year | 查询参数 | 否 | 整数 | 10-K、10-Q 或 20-F 的财年;8-K 则是提交的年份。省略则取最新的申报文件。 |
quarter | 查询参数 | 否 | 整数 | 财季,仅用于季度报告(10-Q、SHIHANKI、분기보고서)。 |
item | 查询参数 | 否 | 字符串 | 一个项目,例如 1A。对于 8-K,结果是公司最近 10 份 8-K 中含有该项目的最新一份(一份 8-K 只报告一件事,所以最新的一份往往没有它);不带 item 则是最新的 8-K。 |
part | 查询参数 | 否 | 字符串 | 部分,I 到 IV。10-Q 在 Part I 有一个 Item 1,在 Part II 还有另一个 Item 1;不带 part 时,item 会同时返回两者。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 申报文件 id。在财务数据中是公司 id。 |
form | 字符串 | 总是 | 申报文件的表格,例如 10-K。 |
sections | 对象数组 | 总是 | 申报文件的项目,按申报文件中的顺序排列。 |
sections[].item | 字符串 | 总是 | 项目编号,例如 1A,8-K 上是 2.02。 |
sections[].title | 字符串 | 总是 | 项目的标题,例如 Risk Factors。 |
sections[].text | 字符串 | 总是 | 项目的文本,与申报时一致。 |
sections[].part | 字符串 | 可选 | 项目所在的部分,I 到 IV。表格没有部分时省略。 |
exhibits | 对象数组 | 可选 | 8-K 的附件文件,以文本形式给出。省略 item 时发送。 |
exhibits[].type | 字符串 | 总是 | 附件类型,例如 EX-99.1。 |
exhibits[].name | 字符串 | 总是 | 附件的文件名。 |
exhibits[].text | 字符串 | 总是 | 附件的文本。 |
exhibits[].truncated | 布尔值 | 可选 | 文本被截断时为 true。 |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/usa:0000320193/sections?form=8-K"{
"id": "usa:0000320193:0001140361-26-042798",
"form": "8-K",
"sections": [
{
"item": "8.01",
"title": "Other Events",
"text": "Other Events.\nOn November 9, 2026, Apple Inc. (“Apple”) consummated the issuance and sale of $500,000,000 aggregate principal amount of its Floating Rate Notes…"
},
{
"item": "9.01",
"title": "Financial Statements and Exhibits",
"text": "Financial Statements and Exhibits.\n(d) Exhibits.\nExhibit\nNumber\nExhibit Description\n1.1 Underwriting Agreement, dated November 5, 2026, among Apple Inc. and Gol…"
}
],
"exhibits": [
{
"type": "EX-1.1",
"name": "ef20085077_ex1-1.htm",
"text": "EX-1.1 2 ef20085077_ex1-1.htm EXHIBIT 1.1\nExhibit 1.1\nApple Inc.\n$500,000,000 Floating Rate Notes due 2028\n$750,000,000 Floating Rate Notes due 2029\n$1,000,000,…"
},
{
"type": "EX-4.1",
"name": "ef20085077_ex4-1.htm",
"text": "EX-4.1 3 ef20085077_ex4-1.htm EXHIBIT 4.1\nExhibit 4.1\nAPPLE INC.\nOfficer’s Certificate\nPursuant to Sections 102 and 301 of the Indenture, dated as of November 1…"
}
]
}列出每种表格的项目
GET /v1/filings/sections/items
文本接口可以返回的各表格的项目:项目、部分和标题。免费:此接口不计费。
先请求项目,再把其中一个作为 item 传给文本接口。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
form | 查询参数 | 否 | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | 一种表格的项目,来自上面三个列表中的任意一个。不带它时,是美国四种表格的项目。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
items | 对象数组 | 总是 | 项目,按表格排列。 |
items[].form | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | 总是 | 该项目所属的表格。 |
items[].item | 字符串 | 总是 | 项目编号,写法与 item 接受的一致。 |
items[].title | 字符串 | 总是 | 项目的标题。 |
items[].part | 字符串 | 可选 | 项目所在的部分。表格没有部分时省略。 |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/filings/sections/items?form=10-K"{
"items": [
{
"form": "10-K",
"item": "1",
"title": "Business",
"part": "I"
},
{
"form": "10-K",
"item": "1A",
"title": "Risk Factors",
"part": "I"
},
{
"form": "10-K",
"item": "1B",
"title": "Unresolved Staff Comments",
"part": "I"
},
{
"form": "10-K",
"item": "1C",
"title": "Cybersecurity",
"part": "I"
}
]
}随财务报表一起获取分部数据
GET /v1/companies/{company_id}/financials
segments=true 会在财务报表响应中加入 segments:公司按分部、产品或地区拆分的收入、营业利润、资产、资本支出、折旧、商誉和长期资产。它与不带该参数的财务数据是同一个接口、同一个价格。各报表的行在 Filings API 页面。
不带 segments=true 时,这是 Filings API 的财务接口,响应中没有 segments。带上后,当某个期间或之后的申报文件给出数字时,会发送 segments。最新期间在前,收入排在其他指标之前。
分部数据跟随响应中的期间,所以 period、fiscal_、as_ 和 version 对它们的截取方式相同。
MCP:工具 filings_。
参数
| 参数 | 位置 | 必填 | 类型 | 含义 |
|---|---|---|---|---|
company_ | 路径参数 | 是 | 字符串 | 公司 id,例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。 |
fields | 查询参数 | 否 | 字符串 | 以逗号分隔的标准项目名称,或 all。省略时为 15 个常用项目。 |
statement | 查询参数 | 否 | one of income, balance, cash_flow, per_share, shares, other | 一张报表的全部项目:income、balance、cash_、per_、shares 或 other。 |
period | 查询参数 | 否 | one of annual, semiannual, quarterly | 默认为 annual,也可用 semiannual 或 quarterly,以登记机构公布的为限。美国公司没有半年报。 |
fiscal_ | 查询参数 | 否 | 整数 | 一个财年。 |
basis | 查询参数 | 否 | one of consolidated, standalone | consolidated 或 standalone。 |
version | 查询参数 | 否 | one of latest, first_reported | 默认为 latest,也可以是 first_。 |
as_ | 查询参数 | 否 | 日期 | 截至这一天已知的数字(YYYY-MM-DD)。 |
segments | 查询参数 | 否 | 布尔值 | true 会加入 segments:针对响应中的期间,申报人按分部、产品或地区拆分的收入、营业利润、资产、资本支出、折旧、商誉和长期资产。标签是公司自己的,使用申报文件的语言,每个数字都带 currency。数字按该期间自身报告中所申报的给出(value、filing_),如果之后的申报文件改变了它,则连同该申报文件以 restated 给出;version=first_ 只返回最初申报的数字。报告尚未为分部数据读取的期间会列在 segments_ 中,其行来自之后的申报文件。该拆分未覆盖的国家的公司返回 404 not_。 |
响应字段
| 字段 | 类型 | 传入 | 含义 |
|---|---|---|---|
id | 字符串 | 总是 | 申报文件 id。在财务数据中是公司 id。 |
currency | 字符串 | 可选 | 报表金额的币种。 |
basis | one of consolidated, standalone | 可选 | consolidated 或 standalone。 |
from_ | 整数 | 可选 | 响应所含的第一个财年,在历史数据被截短时发送。否则省略。 |
annual | 对象数组 | 可选 | 年度行,从新到旧。当 period 要求时,行的键是 semiannual 或 quarterly。行中的项目见 Filings API 页面。 |
semiannual | 对象数组 | 可选 | period=semiannual 时的半年度行。 |
quarterly | 对象数组 | 可选 | period=quarterly 时的季度行。 |
as_ | 日期 | 可选 | 数字所截至的日期。 |
segments | 对象数组 | 可选 | 响应中各期间的拆分,最新期间在前。没有读取过任何期间且之后的申报文件也没有数字时省略。 |
segments[].end | 日期 | 总是 | 期间的结束日期,或该数字的日期。 |
segments[].start | 日期 | 可选 | 期间的开始日期。对某一日期的数字,例如资产或商誉,省略。 |
segments[].measure | one of revenue, operating_income, assets, capex, depreciation, goodwill, long_lived_assets | 总是 | 所衡量的对象:revenue、operating_、assets、capex、depreciation、goodwill 或 long_。 |
segments[].axis | one of segment, product, geography | 总是 | 公司的拆分方式:segment、product 或 geography。 |
segments[].member | 字符串 | 总是 | 公司对该分部、产品或地区的称呼,与其申报文件中的标记一致。 |
segments[].label | 字符串 | 可选 | 公司对该成员自己的措辞。 |
segments[].concept | 字符串 | 总是 | 公司为该数字使用的标签。 |
segments[].value | 字符串 | 可选 | 该期间的报告(filing_)中所申报的数字。restated_ 成员省略。 |
segments[].filing_ | 字符串 | 可选 | value 所申报的申报文件:该期间的第一份报告。 |
segments[].currency | 字符串 | 总是 | 该数字的币种。 |
segments[].percent_ | 字符串 | 可选 | 该值占公司合并数字的百分比,合并数字取自 filing_ 中同一概念、期间和币种,保留两位小数,按远离零的方向四舍五入("37.42")。它是申报文件自己的无维度数字,绝不是各成员之和:申报人会加入小计和合并成员,有些还给未分摊成本前的分部利润标上合并概念,所以成员相加不一定等于 100。当值与合计符号相反时为负(盈利公司中亏损的分部);合并亏损的公司中亏损的分部则为正。如果申报文件没有印出该概念和期间的合并数字(例如合计用了另一个概念标记)、合计为零或币种不同,则省略。 |
segments[].restated | 对象 | 可选 | 之后的申报文件给出的数字,连同该申报文件,在它改变了最初申报的数字时给出。在 restated_ 行中,它是唯一保存的数字,而且可能不是重述。 |
segments[].restated.value | 字符串 | 总是 | 重述后的数字,以 currency 的整单位表示。 |
segments[].restated.filing_ | 字符串 | 总是 | 重述后数字所来自的之后的申报文件。 |
segments[].restated.percent_ | 字符串 | 可选 | 该值占公司合并数字的百分比,合并数字取自 filing_ 中同一概念、期间和币种,保留两位小数,按远离零的方向四舍五入("37.42")。它是申报文件自己的无维度数字,绝不是各成员之和:申报人会加入小计和合并成员,有些还给未分摊成本前的分部利润标上合并概念,所以成员相加不一定等于 100。当值与合计符号相反时为负(盈利公司中亏损的分部);合并亏损的公司中亏损的分部则为正。如果申报文件没有印出该概念和期间的合并数字(例如合计用了另一个概念标记)、合计为零或币种不同,则省略。 |
segments[].restated_ | 恒为 true | 可选 | true 表示没有保存最初申报的数字:该期间的报告中没有这个成员(之后的申报文件把该期间重新切分成其他成员),或者该报告尚未加载(该期间在 segments_ 中)。value 和 filing_ 省略,restated 是唯一的数字,即之后某份申报文件的数字,在第二种情况下甚至可能根本不是重述。报告加载后,该行会出现 value 和 filing_。 |
segments_ | list of date | 可选 | 期末日期,从新到旧,这些期间自身的报告尚未为分部数据读取。它们缺少最初申报的数字,这与没有申报不是一回事;它们的行都是 restated_,来自之后的申报文件。 |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/usa:0001260221/financials?segments=true&period=annual&fiscal_year=2024&statement=income"{
"id": "usa:0001260221",
"currency": "USD",
"annual": [
{
"fy": 2024,
"end": "2024-09-30",
"form": "10-K",
"derived": [],
"revenue": "7940000000",
"gross_profit": "4672000000",
"operating_income": "3531000000",
"net_income": "1714000000"
}
],
"as_of": "2026-11-10",
"segments": [
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "geography",
"member": "country:US",
"label": "UNITED STATES",
"concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
"value": "5032000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "63.38"
},
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "segment",
"member": "tdg:PowerAndControlMember",
"label": "Power And Control [Member]",
"concept": "us-gaap:Revenues",
"value": "3941000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "49.63",
"restated": {
"value": "3966000000",
"filing_id": "usa:0001260221:0001260221-25-000081",
"percent_of_total": "49.95"
}
},
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "geography",
"member": "country:US",
"label": "UNITED STATES",
"concept": "us-gaap:Revenues",
"currency": "USD",
"restated": {
"value": "5032000000",
"filing_id": "usa:0001260221:0001260221-25-000081",
"percent_of_total": "63.38"
},
"restated_only": true
},
{
"end": "2024-09-30",
"measure": "assets",
"axis": "segment",
"member": "tdg:PowerAndControlMember",
"label": "Power And Control [Member]",
"concept": "us-gaap:Assets",
"value": "9139000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "35.72",
"restated": {
"value": "9180000000",
"filing_id": "usa:0001260221:0001260221-25-000014",
"percent_of_total": "35.88"
}
}
]
}错误
错误使用通用的 problem 结构,并带有 request_。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。
| 代码 | 状态 | 含义 |
|---|---|---|
invalid_ | 400 | 参数缺失、未知、重复或超出范围。 |
company_ | 404 | 没有公司与该 id 匹配。 |
filing_ | 404 | 没有申报文件与该 id 匹配,或者该公司没有该表格和该期间的申报文件。 |
item_ | 404 | 该申报文件没有这个项目。对于按公司查询的 8-K,最新的 10 份 8-K 中没有一份有它。 |
sections_ | 404 | 不提供这份申报文件的文本:它的文本尚未读取,不是美国的申报文件,或者无法区分其项目。 |
segments_ | 404 | 该公司的分部数据尚未读取。 |
not_ | 404 | 尚未涵盖该市场、国家或公司。 |
insufficient_ | 402 | 您的额度余额低于该请求的费用。 |
company_ | 503 | 该接口背后的申报文件目前无法读取。请稍后重试。 |
此页面对你有帮助吗?