瀏覽全部文件

申報文件文字與營運部門 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。營運部門資料僅適用於美國公司。

基礎網址: 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_idpath是字串申報文件 ID:公司 ID、一個冒號與 SEC 收件編號,例如 usa:0000320193:0000320193-26-000026。Filings API 會列出它們。
itemquery否字串依編號指定的一個項目,例如 1A 或 7。8-K 的項目形如 2.02。省略則回傳全部項目。申報文件沒有的項目會得到 404 item_not_found。
partquery否字串部分(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 中含有該項目的最新一份。

搭配 form=10-Q 使用 quarter 來選擇季度。與其他任何表格一起使用會得到 400 invalid_query。

MCP:工具 filings_get_company_sections。

參數

參數位置必填類型含義
company_idpath是字串公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。
formquery是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。
yearquery否整數10-K、10-Q 或 20-F 的會計年度;8-K 則是提交的年份。省略則取最新的申報文件。
quarterquery否整數會計季度,僅適用於季度報告(10-Q、SHIHANKI、분기보고서)。
itemquery否字串一個項目,例如 1A。若是 8-K,結果是公司最近 10 份 8-K 中含有該項目的最新一份(一份 8-K 只報告一件事,所以最新的一份常常沒有它);未帶 item 則是最新的 8-K。
partquery否字串部分,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。

參數

參數位置必填類型含義
formquery否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_idpath是字串公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。
fieldsquery否字串以逗號分隔的標準項目名稱,或 all。省略時為 15 個常用項目。
statementquery否one of income, balance, cash_flow, per_share, shares, other一張報表的所有項目:income、balance、cash_flow、per_share、shares 或 other。
periodquery否one of annual, semiannual, quarterly預設為 annual,也可用 semiannual 或 quarterly,以登記機構公布的為限。美國公司沒有半年報。
fiscal_yearquery否整數一個會計年度。
basisquery否one of consolidated, standaloneconsolidated 或 standalone。
versionquery否one of latest, first_reported預設為 latest,也可以是 first_reported。
as_ofquery否日期截至這一天已知的數字(YYYY-MM-DD)。
segmentsquery否布林值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"
      }
    }
  ]
}

錯誤

錯誤使用共用的問題格式,並包含 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這個路由背後的申報文件目前無法讀取。請稍後再試。

此頁面對你有幫助嗎?