申報文件文字與營運部門 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_。營運部門資料僅適用於美國公司。
基礎網址: 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_ | path | 是 | 字串 | 申報文件 ID:公司 ID、一個冒號與 SEC 收件編號,例如 usa:0000320193:0000320193-26-000026。Filings API 會列出它們。 |
item | query | 否 | 字串 | 依編號指定的一個項目,例如 1A 或 7。8-K 的項目形如 2.02。省略則回傳全部項目。申報文件沒有的項目會得到 404 item_。 |
part | query | 否 | 字串 | 部分(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_。
MCP:工具 filings_。
參數
| 參數 | 位置 | 必填 | 類型 | 含義 |
|---|---|---|---|---|
company_ | path | 是 | 字串 | 公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。 |
form | query | 是 | 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 | query | 否 | 整數 | 10-K、10-Q 或 20-F 的會計年度;8-K 則是提交的年份。省略則取最新的申報文件。 |
quarter | query | 否 | 整數 | 會計季度,僅適用於季度報告(10-Q、SHIHANKI、분기보고서)。 |
item | query | 否 | 字串 | 一個項目,例如 1A。若是 8-K,結果是公司最近 10 份 8-K 中含有該項目的最新一份(一份 8-K 只報告一件事,所以最新的一份常常沒有它);未帶 item 則是最新的 8-K。 |
part | query | 否 | 字串 | 部分,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 | query | 否 | 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_ | path | 是 | 字串 | 公司 ID,例如 usa:0000320193。也接受股票代號別名,例如 usa:AAPL。 |
fields | query | 否 | 字串 | 以逗號分隔的標準項目名稱,或 all。省略時為 15 個常用項目。 |
statement | query | 否 | one of income, balance, cash_flow, per_share, shares, other | 一張報表的所有項目:income、balance、cash_、per_、shares 或 other。 |
period | query | 否 | one of annual, semiannual, quarterly | 預設為 annual,也可用 semiannual 或 quarterly,以登記機構公布的為限。美國公司沒有半年報。 |
fiscal_ | query | 否 | 整數 | 一個會計年度。 |
basis | query | 否 | one of consolidated, standalone | consolidated 或 standalone。 |
version | query | 否 | one of latest, first_reported | 預設為 latest,也可以是 first_。 |
as_ | query | 否 | 日期 | 截至這一天已知的數字(YYYY-MM-DD)。 |
segments | query | 否 | 布林值 | 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"
}
}
]
}錯誤
錯誤使用共用的問題格式,並包含 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 | 這個路由背後的申報文件目前無法讀取。請稍後再試。 |
此頁面對你有幫助嗎?