申报文件 API 参考

通过 REST 和 MCP 读取官方登记机构的公司财务数据、申报文件及持股比例达到或超过 5% 的股东。

八项操作涵盖公司搜索与基本信息、财务报表、公司申报文件列表、单份申报文件、最新申报文件、持股比例为 5% 或以上的股东，以及按申报原样提供的财务数据。报告来自 SEC EDGAR、EDINET、DART、欧盟/欧洲经济区年度报告登记机构和台湾。

REST 和 MCP 共用 Bearer 密钥、模式和配额；每个请求计为一次调用。先通过搜索找到公司，再使用返回的 id 请求该公司的数据。

操作

操作	REST 路径	MCP 工具	返回内容
搜索公司	`GET /v1/companies`	`filings_search_companies`	匹配的公司
获取公司	`GET /v1/companies/{company_id}`	`filings_get_company`	公司基本信息与证券
获取财务数据	`GET /v1/companies/{company_id}/financials`	`filings_get_financials`	按期间列出的标准财务项目
列出公司申报文件	`GET /v1/companies/{company_id}/filings`	`filings_list_company_filings`	公司申报文件，按时间从新到旧排列
获取申报文件	`GET /v1/filings/{filing_id}`	`filings_get_filing`	申报文件详情与官方链接
最新申报文件	`GET /v1/filings/latest`	`filings_list_latest_filings`	各公司的最新申报文件
股东	`GET /v1/companies/{company_id}/holders`	`filings_list_holders`	已披露的持股比例为 5% 或以上的股东
申报原始数据	`GET /v1/filings/{filing_id}/financials/as-reported`	`filings_get_as_reported`	完全按原始标记提供的财务数据

每个请求都需要 Bearer 密钥；REST 请求使用 Authorization: Bearer $NARWHAL_API_KEY。身份验证

公司与申报文件 ID

使用搜索返回的公司 id；台湾公司的 ID 以 twn: 为前缀，后接搜索返回的代码。

登记机构	公司 ID	示例
SEC EDGAR，美国	`usa:<CIK>`	`usa:0000320193`
EDINET，日本	`jpn:<EDINET code>`	`jpn:E02144`
DART，韩国	`kor:<corp code>`	`kor:00126380`
欧盟与欧洲经济区年度报告	`<iso3>:<LEI>`	`prt:213800NI6JNPX5F44U15`

申报文件 ID 由公司 ID 和登记机构的受理编号组成，两者以冒号分隔，例如 usa:0000320193:0000320193-25-000079。

公司路径支持使用 usa:AAPL 这样的股票代码别名，并将其解析为公司 ID。

搜索公司

按名称、股票代码或公司代码查找公司，可选择按国家和登记机构筛选。使用 as_of 选择特定日期生效的股票代码。

q：公司名称、股票代码或公司代码，最多 200 个字符。
country：大写三字母国家代码。
registry：小写登记机构代码，例如 usa、jpn 或 kor。
as_of：用于选择当时生效的股票代码的日期。
lang：默认为 en，也可设为 original。
limit：返回 1 至 100 条结果，默认为 20。

companies 列表包含公司基本信息和上市详情。matched 通过 id、code、name、former_code 或 former_name 说明匹配依据；适用时还会返回曾用名和取值为 true 的 delisted 标志。未提供 q 时，响应还包含 coverage，表示每个登记机构已加载的公司数量。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies?q=AAPL&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc.",
      "country": "USA",
      "mic": "XNAS",
      "code": "AAPL",
      "matched": "code"
    }
  ]
}

获取公司

读取公司的基本信息、报告准则、名称历史、证券和关联公司。

as_of：用于选择当时生效的股票代码的日期。
lang：默认为 en，也可设为 original。

基本信息包括可获取的法定标识符、行业分类和状态详情。fiscal_year_end 使用 MMDD 格式，例如 0926 表示 9 月 26 日；standard 标明 us_gaap、ifrs、j_gaap、jmis 或 k_gaap。names 记录曾用名及其日期；securities 描述股份类别、类型、标识符和带日期的上市记录；related 标明交叉上市公司、继承公司或前身公司。这三个字段始终为列表。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "name": "Apple Inc.",
  "country": "USA",
  "fiscal_year_end": "0926",
  "standard": "us_gaap",
  "industry": {
    "isic": "2620",
    "sector": "Manufacturing",
    "industry": "Manufacture of computer, electronic and optical products",
    "source_scheme": "us_sic",
    "source_code": "3571"
  },
  "names": [
    {
      "name": "APPLE INC",
      "from": "2007-01-10",
      "to": "2019-08-05"
    },
    {
      "name": "APPLE COMPUTER INC",
      "from": "1994-01-26",
      "to": "2007-01-04"
    },
    {
      "name": "APPLE COMPUTER INC/ FA",
      "from": "1997-07-28",
      "to": "1997-07-28"
    }
  ],
  "securities": [
    {
      "class": "common",
      "type": "common",
      "primary": true,
      "listings": [
        {
          "mic": "XNAS",
          "code": "AAPL",
          "from": "2026-10-20"
        }
      ]
    }
  ],
  "related": []
}

获取财务数据

读取公司各财务期间的标准财务项目，按时间从新到旧排列。响应根据 period 使用 annual、semiannual 或 quarterly 作为行键。

fields：以逗号分隔的标准项目名称，或 all；默认返回 15 个常用项目。
statement：选择 income、balance、cash_flow、per_share、shares 或 other 中的全部项目。
period：默认为 annual，也可设为 semiannual 或 quarterly，受登记机构和套餐限制。
fiscal_year：套餐允许的历史范围内的一个财年。
basis：consolidated 或 standalone。
version：默认为 latest；first_reported 需要 Pro。
as_of：截至指定日期已知的数据；需要 Pro。

共有 77 个标准项目：29 个利润表项目、28 个资产负债表项目、14 个现金流量项目、3 个每股项目和 3 个股本项目。使用 fields 按名称选择项目，使用 fields=all 获取全部项目，或使用 statement 选择报表。默认的 15 个项目为 revenue、gross_profit、operating_income、net_income、cash、total_assets、total_debt、total_liabilities、total_equity、operating_cash_flow、capex、free_cash_flow、eps_diluted、dividend_per_share 和 shares_outstanding。未知字段名称会返回 400 unknown_field。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?fields=revenue,net_income,total_assets,eps_diluted" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "currency": "USD",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "derived": [],
      "revenue": "416161000000",
      "net_income": "112010000000",
      "total_assets": "359241000000",
      "eps_diluted": "7.46"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "derived": [],
      "revenue": "391035000000",
      "net_income": "93736000000",
      "total_assets": "364980000000",
      "eps_diluted": "6.08"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "derived": [],
      "revenue": "383285000000",
      "net_income": "96995000000",
      "total_assets": "352583000000",
      "eps_diluted": "6.13"
    }
  ]
}

金额以申报文件所用币种的十进制字符串表示，不进行货币换算或数值缩放。缺失项目会被省略，申报值为零时仍保留为 "0"。每行标明财年和期间结束日期，适用时还会标明财季或上、下半年；derived 列出由 Narwhal 计算的项目，例如 free_cash_flow。数据始终以官方申报文件为准。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?statement=per_share" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "7.46",
      "dividend_per_share": "1.02"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.08",
      "dividend_per_share": "0.98"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.13",
      "dividend_per_share": "0.94"
    }
  ]
}

日本发布年度和半年度报告，不发布季度报告。美国公司发布年度和季度报告，不发布半年度报告；台湾也不发布半年度报告。欧盟/欧洲经济区的报告为年度报告。请求登记机构不发布的报告期间时，会返回 404 period_not_published，并在详情中说明应使用的期间。

列出公司申报文件

读取公司的申报文件，可按类型、表单和申报日期筛选。

type：annual、semiannual、quarterly、event、ownership、insider 或 other。
form：准确的表单名称，例如 10-K，最多 20 个字符。
filed_from：申报起始日期。
filed_to：申报截止日期。
include_amendments：是否包含修订文件，默认为 false。
cursor：使用相同筛选条件获取下一页的游标。
limit：返回 1 至 200 条结果，默认为 50。
lang：默认为 en，也可设为 original。

每行标明申报文件、申报日期、表单、类型和期间结束日期；登记机构提供标题时，也会包含标题。结果按时间从新到旧排列；使用 next_cursor 获取下一页，最后一页的值为 null。套餐限制导致起始日期向后调整时，响应会回显 filed_from。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/filings?type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "filings": [
    {
      "id": "usa:0000320193:0000320193-25-000079",
      "filed": "2025-10-31",
      "form": "10-K",
      "type": "annual",
      "period_end": "2025-09-27"
    },
    {
      "id": "usa:0000320193:0000320193-24-000123",
      "filed": "2024-11-01",
      "form": "10-K",
      "type": "annual",
      "period_end": "2024-09-28"
    }
  ],
  "next_cursor": "eyJpIjo0MTUwNjcsImtpbmQiOiJmaWxpbmdzIiwicSI6IjExYzkyYjY4YWJjZTMyM2YiLCJ0IjoiMjAyNC0xMS0wMVQxMDowMTozNiswMDowMCIsInYiOjF9.j2L56WYc-pkZ4UoI0z1vAN4htuG4nzEDOJUTtT_CZOY"
}

获取申报文件

读取单份申报文件的元数据和登记机构官方链接；lang 默认为 en，也可设为 original。

响应标明申报文件和公司；申报主体与公司不同时，还会包含 filer_id。响应包括表单、类型、标题、财年、期间结束日期，以及可获取时的 UTC 时间戳 filed_at。fp 标明 FY、H1、H2 或 Q1 至 Q4；url 链接至登记机构的官方申报文件页面。amends 标明被修订的申报文件，withdrawn 仅在值为 true 时出现。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193:0000320193-25-000079",
  "company_id": "usa:0000320193",
  "form": "10-K",
  "type": "annual",
  "fy": 2025,
  "fp": "FY",
  "period_end": "2025-09-27",
  "filed_at": "2025-10-31T10:01:26Z",
  "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm"
}

持股比例达到或超过 5% 的股东

读取美国、日本和韩国持股申报文件中披露的股东。列表采用每位股东的最新报告，并移除已退出的股东。

security：股份类别，最多 40 个字符。
lang：默认为 en，也可设为 original。
limit：返回 1 至 500 条结果，默认为 100。

每行列出可获取的股东、持股比例、持股数量、事件日期、申报日期、申报文件 ID 和证券。列表不分页。当套餐将起始日期后移时，响应会返回调整后的 filed_from。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/holders?limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "holders": [
    {
      "holder": "Vanguard Capital Management",
      "percent": "7.48",
      "shares": "1099168953",
      "event_date": "2026-03-31",
      "filed": "2026-04-30",
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "security": {
        "class": "common"
      }
    }
  ]
}

原始披露财务数据

按原始标签读取一份申报文件中的财务数据，并按概念分组。所有套餐均可在申报文件查询中使用此操作。

concepts 中的每个条目均包含 taxonomy、concept、label、unit 和一个 values 列表。每个数值条目包含数据中存在的 start、end 和 value。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079/financials/as-reported" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "concepts": [
    {
      "taxonomy": "us-gaap",
      "concept": "Revenues",
      "label": "Revenues",
      "unit": "USD",
      "values": [
        {
          "start": "2023-10-01",
          "end": "2024-09-28",
          "value": "391035000000"
        },
        {
          "start": "2022-09-25",
          "end": "2023-09-30",
          "value": "383285000000"
        }
      ]
    }
  ]
}

仅支持美国申报文件；日本和韩国的申报文件返回 404 as_reported_unavailable。一份申报文件可能包含数千项数据，因此响应大小可能达到数百千字节。结果不分页。

套餐限制

所有套餐均可使用全部操作和标准项目；套餐决定历史数据范围和交付时效。

	免费	Basic	Pro
财务历史数据	最近 3 个财年	最近 10 个财年	完整历史数据
报告期	年度	年度、半年度、季度	年度、半年度、季度
申报文件列表和股东	最近 3 年	最近 10 年	完整历史数据
交付	次日	在线	在线
首次披露及截至指定日期的数据	否	否	是

如果请求仅起始时间早于允许范围，则会截取为套餐的历史数据范围，财务数据使用 from_fy，申报文件和股东数据使用 filed_from。申报文件和股东数据的范围按自然年计算；Free 仅提供在今天 00:00 UTC 之前提交的申报文件。

以下请求会在扣除任何配额之前返回 403 plan_upgrade_required：Free 请求季度或半年度财务数据，fiscal_year 早于历史数据范围，filed_to 早于该范围，或低于 Pro 的套餐使用 version=first_reported 或 as_of 请求财务数据。

响应约定

数值以十进制字符串表示。
缺失的标量字段会被省略，绝不返回 null。
列表始终存在，为空时返回 []。
delisted 和 withdrawn 等标志仅在值为真时出现。
最后一页的 next_cursor 为 null。
lang=original 在有相应数据时，以登记机构使用的语言返回名称和标题；默认值为 en。

错误

400 invalid_query 查询无效。
400 unknown_field fields 中的某个名称不是标准财务项目。
400 invalid_cursor 游标格式错误，或该游标是针对其他筛选条件生成的。
401 invalid_api_key API 密钥无效。
403 plan_upgrade_required 请求的历史数据范围、报告期或财务数据版本超出套餐权限。
404 company_not_found 未找到该公司。
404 filing_not_found 未找到该申报文件。
404 period_not_published 登记机构未发布所请求报告期的数据；详细信息中列出了应使用的报告期。
404 as_reported_unavailable 该申报文件的原始披露财务数据不可用。
429 rate_limit_exceeded 已超出请求频率限制。
429 quota_exhausted 请求配额已用尽。
503 database_unavailable 数据存储不可用；请重试请求。

错误采用标准问题响应结构。错误与配额

身份验证文档介绍 Bearer 密钥，错误文档介绍标准问题响应结构，MCP 文档介绍工具访问方式。身份验证 · 错误与配额 · MCP