API 參考
API 文件
這是一個唯讀的 JSON API,與本站頁面使用同一份行情資料。成功回應使用 { data, meta } 封裝;失敗回應使用 { error: { code, message } }。
- 基礎 URL
- http://localhost:3000
- 方法
- 僅支援 GET
- 格式
- JSON、UTF-8
- 限流
- 每個 IP、每個端點在 60 秒內最多 60 次請求
These are API examples. This site is served as static files.
示範
除非伺服器同時設定
MARKET_DATA_PROVIDER=fmp 與 FMP_API_KEY,否則回應用的是公司名稱虛構的確定性示範資料集。每個回應的 meta.provider 欄位會說明是由哪個資料來源回應的。查詢報價列表
GET
/api/quotes以一維陣列回傳一頁交易標的,meta 中包含 total、page 與 pageSize。下方所有篩選條件在此同樣適用;無法解析的數值會被忽略。
參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
| sector | query | string | 選填 | 精確的產業名稱:Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate。 |
| sort | query | string | 選填 | 排序欄位:marketCap(預設)、price、changePercent、volume 或 symbol。 |
| order | query | string | 選填 | 排序方向:desc(預設)或 asc。 |
| page | query | number | 選填 | 頁碼,從 1 開始。 |
| pageSize | query | number | 選填 | 每頁列數:預設 20,最多 100。 |
請求
curl -s "http://localhost:3000/api/quotes?pageSize=3"回應範例
200application/json
{
"data": [
{
"symbol": "NWRB",
"name": "Northwind Robotics",
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Industrial Automation",
"price": 733.8,
"change": -16.52,
"changePercent": -2.2,
"previousClose": 750.32,
"open": 750.03,
"dayHigh": 751.29,
"dayLow": 731.5,
"volume": 3471317,
"avgVolume": 2962633,
"marketCap": 982258754565,
"peRatio": 60.35,
"eps": 12.16,
"dividendYield": null,
"week52High": 963.99,
"week52Low": 583.89,
"afterHoursPrice": 731,
"afterHoursChangePercent": -0.38,
"updatedAt": "2026-11-12T21:00:00.000Z"
}
],
"meta": {
"provider": "demo",
"generatedAt": "2026-11-12T21:00:04.512Z",
"disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
"total": 20,
"page": 1,
"pageSize": 3
}
}範例僅保留一列。
查詢單一報價
GET
/api/quotes/{symbol}回傳單一交易標的或指數的完整報價。未知代號回傳 404 not_found。
參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
| symbol | path | string | 必填 | 交易標的或指數代號,例如 NWRB。比對時忽略大小寫。 |
請求
curl -s "http://localhost:3000/api/quotes/NWRB"回應範例
200application/json
{
"data": {
"symbol": "NWRB",
"name": "Northwind Robotics",
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Industrial Automation",
"price": 733.8,
"change": -16.52,
"changePercent": -2.2,
"previousClose": 750.32,
"open": 750.03,
"dayHigh": 751.29,
"dayLow": 731.5,
"volume": 3471317,
"avgVolume": 2962633,
"marketCap": 982258754565,
"peRatio": 60.35,
"eps": 12.16,
"dividendYield": null,
"week52High": 963.99,
"week52Low": 583.89,
"afterHoursPrice": 731,
"afterHoursChangePercent": -0.38,
"updatedAt": "2026-11-12T21:00:00.000Z"
},
"meta": {
"provider": "demo",
"generatedAt": "2026-11-12T21:00:04.512Z",
"disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice."
}
}查詢 K 線
GET
/api/candles/{symbol}依時間由早到晚回傳 OHLCV K 線。1D 區間使用 30 分鐘粒度,其餘區間使用日線。未知區間回傳 400 bad_request。
參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
| symbol | path | string | 必填 | 交易標的或指數代號,例如 NWRB。比對時忽略大小寫。 |
| range | query | string | 選填 | 1D, 5D, 1M, 6M, 1Y, 5Y 之一,預設 1M。 |
請求
curl -s "http://localhost:3000/api/candles/NWRB?range=1M"回應範例
200application/json
{
"data": [
{
"time": "2026-11-11",
"open": 757.4,
"high": 761.18,
"low": 743.92,
"close": 750.32,
"volume": 3531710
},
{
"time": "2026-11-12",
"open": 750.03,
"high": 751.29,
"low": 731.5,
"close": 733.8,
"volume": 3471317
}
],
"meta": {
"provider": "demo",
"generatedAt": "2026-11-12T21:00:04.512Z",
"disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
"symbol": "NWRB",
"range": "1M"
}
}範例僅保留兩根 K 線;1M 區間回傳 22 根。
篩選交易標的
GET
/api/screener使用與篩選器頁面相同的參數進行過濾、排序與分頁。結果包含 rows 以及 total、page、pageSize;無法解析的數值會被忽略。
參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
| sector | query | string | 選填 | 精確的產業名稱:Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate。 |
| minMarketCap, maxMarketCap | query | number | 選填 | 市值上下限,單位為美元。 |
| minPrice, maxPrice | query | number | 選填 | 價格上下限,單位為美元。 |
| minChangePercent, maxChangePercent | query | number | 選填 | 當日漲跌幅上下限,單位為百分點:-3 代表 -3%。 |
| minVolume | query | number | 選填 | 最小日成交量,單位為股。 |
| profitableOnly | query | string | 選填 | 設為 1 時僅保留 EPS 大於 0 的交易標的。 |
| sort | query | string | 選填 | 排序欄位:marketCap(預設)、price、changePercent、volume 或 symbol。 |
| order | query | string | 選填 | 排序方向:desc(預設)或 asc。 |
| page | query | number | 選填 | 頁碼,從 1 開始。 |
| pageSize | query | number | 選填 | 每頁列數:預設 20,最多 100。 |
請求
curl -s "http://localhost:3000/api/screener?profitableOnly=1&pageSize=5"回應範例
200application/json
{
"data": {
"rows": [
{
"symbol": "NWRB",
"name": "Northwind Robotics",
"exchange": "NASDAQ",
"sector": "Technology",
"industry": "Industrial Automation",
"price": 733.8,
"change": -16.52,
"changePercent": -2.2,
"previousClose": 750.32,
"open": 750.03,
"dayHigh": 751.29,
"dayLow": 731.5,
"volume": 3471317,
"avgVolume": 2962633,
"marketCap": 982258754565,
"peRatio": 60.35,
"eps": 12.16,
"dividendYield": null,
"week52High": 963.99,
"week52Low": 583.89,
"afterHoursPrice": 731,
"afterHoursChangePercent": -0.38,
"updatedAt": "2026-11-12T21:00:00.000Z"
}
],
"total": 17,
"page": 1,
"pageSize": 5
},
"meta": {
"provider": "demo",
"generatedAt": "2026-11-12T21:00:04.512Z",
"disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
"total": 17,
"page": 1,
"pageSize": 5
}
}範例僅保留一列。
身分驗證
示範模式無需金鑰。當伺服器設定 API_KEY 環境變數後,每個請求都必須在 X-API-Key 標頭中攜帶相同的值;否則會收到 401 unauthorized。
curl -s "http://localhost:3000/api/quotes/NWRB" \
-H "X-API-Key: your-key-here"注意
金鑰只在伺服器端讀取。本頁的送出請求按鈕從瀏覽器直接呼叫 API 且不帶金鑰,因此在啟用金鑰驗證時會回傳 401。
錯誤碼
失敗的請求會回傳對應的 HTTP 狀態碼與一個錯誤物件。請依 code 分支處理;message 是給人看的,可能隨時調整。
{
"error": {
"code": "not_found",
"message": "A human-readable explanation."
}
}| HTTP 狀態碼 | 錯誤碼 | 觸發條件 |
|---|---|---|
| 400 | bad_request | 某個參數值不被允許,例如未知的 K 線區間。 |
| 401 | unauthorized | 已設定 API_KEY,而請求沒有攜帶相符的 X-API-Key 標頭。 |
| 404 | not_found | 該代號不在資料集中。 |
| 405 | method_not_allowed | API 為唯讀:/api/quotes 收到 POST 時回傳此錯誤碼。 |
| 429 | rate_limited | 同一 IP 對同一端點在 60 秒內請求超過 60 次。回應會包含以秒為單位的 Retry-After。 |