申報文件 API 參考文件

透過 REST 及 MCP，讀取官方登記機關提供的公司財務資料、申報文件及持股 5% 以上的股東資料。

八項操作涵蓋公司搜尋與基本資料、財務報表、公司申報文件清單、個別申報文件、最新申報文件、持股 5% 以上的股東，以及原始申報財務數據。報告來自 SEC EDGAR、EDINET、DART、EU/EEA 年報申報資料庫與台灣。

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`
EU 與 EEA 年報	`<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"
    }
  ]
}

日本發布年度與半年度報告，不發布季度報告。美國公司發布年度與季度報告，不發布半年度報告；台灣也沒有半年度報告。EU/EEA 的報告為年度報告。若查詢申報資料庫未發布的期間，會傳回 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。單一申報文件可能包含數千筆財務事實，因此回應大小可能達數百 KB。結果不分頁。

方案限制

所有方案均可使用全部操作及標準項目；歷史資料範圍及交付時效依方案而定。

	免費	Basic	Pro
財務歷史資料	最近 3 個會計年度	最近 10 個會計年度	完整歷史資料
期間	年度	年度、半年度、季度	年度、半年度、季度
申報文件清單及股東	最近 3 年	最近 10 年	完整歷史資料
交付	次日	在線	在線
首次公布及截至指定日期的數值	否	否	是

若請求僅有起始時間過早，會將其調整至方案允許的範圍，財務資料使用 from_fy，申報文件及股東資料使用 filed_from。申報文件及股東資料的範圍以曆年計算；Free 僅提供今日 00:00 UTC 之前申報的文件。

Free 請求季度或半年度財務資料、fiscal_year 早於歷史資料範圍、filed_to 早於該範圍，或低於 Pro 的方案請求帶有 version=first_reported 或 as_of 的財務資料時，皆會在扣除任何配額前回傳 403 plan_upgrade_required。

回應慣例

數字以十進位字串表示。
缺少的純量欄位會省略，絕不以 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