浏览全部文档

申报文件文本与分部 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_unavailable;某一期间自身的报告尚未为分部数据读取时,该期间会列在 segments_unread 中。

文本接口支持美国、日本和韩国。美国的申报文件是 10-K、10-Q、20-F 或 8-K。日本的申报文件是 YUHO、HANKI、SHIHANKI 或 RINJI,韩国的是 사업보고서、반기보고서 或 분기보고서。属于公司所在国以外国家的表格返回 400 invalid_query。其他任何国家的公司返回 404 not_covered。文本尚未读取的日本或韩国申报文件返回 404 sections_unavailable。分部数据只适用于美国公司。

基础 URL: https://api.narwhalapi.com。 下面每个路由都是一个独立的 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_id 所指申报文件中同一概念和期间,保留两位小数。成员相加不一定等于 100,因为申报人会加入小计和合并成员。如果该申报文件没有印出该概念和期间的合并数字,则省略。
  • 分部数字以 currency 的整单位表示。某一日期的数字,例如资产或商誉,没有 start。

端点

每个路由都是 GET 请求,并需要在以下请求头中携带你的密钥: Authorization: Bearer 标头。示例仅展示响应的结构,并非实时数据。

按项目获取申报文件的文本

GET /v1/filings/{filing_id}/sections

一份申报文件的文本,按项目标题切分:全部项目,或用 item 取一个项目。可以是美国的 10-K、10-Q、20-F 或 8-K,也可以是日本或韩国的报告。无法区分项目的申报文件返回 404 sections_unavailable,绝不返回部分文本。

MCP:工具 filings_get_sections。

参数

参数位置必填类型含义
filing_id路径参数是字符串申报文件 id:公司 id、一个冒号和 SEC 受理编号,例如 usa:0000320193:0000320193-26-000026。Filings API 会列出它们。
item查询参数否字符串按编号指定的一个项目,例如 1A 或 7。8-K 的项目形如 2.02。省略则返回全部项目。申报文件没有的项目返回 404 item_not_found。
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_query。

MCP:工具 filings_get_company_sections。

参数

参数位置必填类型含义
company_id路径参数是字符串公司 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_query。
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_list_section_items。

参数

参数位置必填类型含义
form查询参数否one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서一种表格的项目,来自上面三个列表中的任意一个。不带它时,是美国四种表格的项目。

响应字段

字段类型传入含义
items对象数组总是项目,按表格排列。
items[].formone 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_year、as_of 和 version 对它们的截取方式相同。

MCP:工具 filings_get_financials。

参数

参数位置必填类型含义
company_id路径参数是字符串公司 id,例如 usa:0000320193。也接受 usa:AAPL 这样的股票代码别名。
fields查询参数否字符串以逗号分隔的标准项目名称,或 all。省略时为 15 个常用项目。
statement查询参数否one of income, balance, cash_flow, per_share, shares, other一张报表的全部项目:income、balance、cash_flow、per_share、shares 或 other。
period查询参数否one of annual, semiannual, quarterly默认为 annual,也可用 semiannual 或 quarterly,以登记机构公布的为限。美国公司没有半年报。
fiscal_year查询参数否整数一个财年。
basis查询参数否one of consolidated, standaloneconsolidated 或 standalone。
version查询参数否one of latest, first_reported默认为 latest,也可以是 first_reported。
as_of查询参数否日期截至这一天已知的数字(YYYY-MM-DD)。
segments查询参数否布尔值true 会加入 segments:针对响应中的期间,申报人按分部、产品或地区拆分的收入、营业利润、资产、资本支出、折旧、商誉和长期资产。标签是公司自己的,使用申报文件的语言,每个数字都带 currency。数字按该期间自身报告中所申报的给出(value、filing_id),如果之后的申报文件改变了它,则连同该申报文件以 restated 给出;version=first_reported 只返回最初申报的数字。报告尚未为分部数据读取的期间会列在 segments_unread 中,其行来自之后的申报文件。该拆分未覆盖的国家的公司返回 404 not_covered。

响应字段

字段类型传入含义
id字符串总是申报文件 id。在财务数据中是公司 id。
currency字符串可选报表金额的币种。
basisone of consolidated, standalone可选consolidated 或 standalone。
from_fy整数可选响应所含的第一个财年,在历史数据被截短时发送。否则省略。
annual对象数组可选年度行,从新到旧。当 period 要求时,行的键是 semiannual 或 quarterly。行中的项目见 Filings API 页面。
semiannual对象数组可选period=semiannual 时的半年度行。
quarterly对象数组可选period=quarterly 时的季度行。
as_of日期可选数字所截至的日期。
segments对象数组可选响应中各期间的拆分,最新期间在前。没有读取过任何期间且之后的申报文件也没有数字时省略。
segments[].end日期总是期间的结束日期,或该数字的日期。
segments[].start日期可选期间的开始日期。对某一日期的数字,例如资产或商誉,省略。
segments[].measureone of revenue, operating_income, assets, capex, depreciation, goodwill, long_lived_assets总是所衡量的对象:revenue、operating_income、assets、capex、depreciation、goodwill 或 long_lived_assets。
segments[].axisone of segment, product, geography总是公司的拆分方式:segment、product 或 geography。
segments[].member字符串总是公司对该分部、产品或地区的称呼,与其申报文件中的标记一致。
segments[].label字符串可选公司对该成员自己的措辞。
segments[].concept字符串总是公司为该数字使用的标签。
segments[].value字符串可选该期间的报告(filing_id)中所申报的数字。restated_only 成员省略。
segments[].filing_id字符串可选value 所申报的申报文件:该期间的第一份报告。
segments[].currency字符串总是该数字的币种。
segments[].percent_of_total字符串可选该值占公司合并数字的百分比,合并数字取自 filing_id 中同一概念、期间和币种,保留两位小数,按远离零的方向四舍五入("37.42")。它是申报文件自己的无维度数字,绝不是各成员之和:申报人会加入小计和合并成员,有些还给未分摊成本前的分部利润标上合并概念,所以成员相加不一定等于 100。当值与合计符号相反时为负(盈利公司中亏损的分部);合并亏损的公司中亏损的分部则为正。如果申报文件没有印出该概念和期间的合并数字(例如合计用了另一个概念标记)、合计为零或币种不同,则省略。
segments[].restated对象可选之后的申报文件给出的数字,连同该申报文件,在它改变了最初申报的数字时给出。在 restated_only 行中,它是唯一保存的数字,而且可能不是重述。
segments[].restated.value字符串总是重述后的数字,以 currency 的整单位表示。
segments[].restated.filing_id字符串总是重述后数字所来自的之后的申报文件。
segments[].restated.percent_of_total字符串可选该值占公司合并数字的百分比,合并数字取自 filing_id 中同一概念、期间和币种,保留两位小数,按远离零的方向四舍五入("37.42")。它是申报文件自己的无维度数字,绝不是各成员之和:申报人会加入小计和合并成员,有些还给未分摊成本前的分部利润标上合并概念,所以成员相加不一定等于 100。当值与合计符号相反时为负(盈利公司中亏损的分部);合并亏损的公司中亏损的分部则为正。如果申报文件没有印出该概念和期间的合并数字(例如合计用了另一个概念标记)、合计为零或币种不同,则省略。
segments[].restated_only恒为 true可选true 表示没有保存最初申报的数字:该期间的报告中没有这个成员(之后的申报文件把该期间重新切分成其他成员),或者该报告尚未加载(该期间在 segments_unread 中)。value 和 filing_id 省略,restated 是唯一的数字,即之后某份申报文件的数字,在第二种情况下甚至可能根本不是重述。报告加载后,该行会出现 value 和 filing_id。
segments_unreadlist of date可选期末日期,从新到旧,这些期间自身的报告尚未为分部数据读取。它们缺少最初申报的数字,这与没有申报不是一回事;它们的行都是 restated_only,来自之后的申报文件。
请求
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_id。查看 API 错误码与额度 了解该结构和额度相关的响应头。失败的请求不计费。

代码状态含义
invalid_query400参数缺失、未知、重复或超出范围。
company_not_found404没有公司与该 id 匹配。
filing_not_found404没有申报文件与该 id 匹配,或者该公司没有该表格和该期间的申报文件。
item_not_found404该申报文件没有这个项目。对于按公司查询的 8-K,最新的 10 份 8-K 中没有一份有它。
sections_unavailable404不提供这份申报文件的文本:它的文本尚未读取,不是美国的申报文件,或者无法区分其项目。
segments_unavailable404该公司的分部数据尚未读取。
not_covered404尚未涵盖该市场、国家或公司。
insufficient_credits402您的额度余额低于该请求的费用。
company_data_unavailable503该接口背后的申报文件目前无法读取。请稍后重试。

此页面对你有帮助吗?