跳至主要內容

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。下方所有篩選條件在此同樣適用;無法解析的數值會被忽略。

參數

參數位置類型必填說明
sectorquerystring選填精確的產業名稱:Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate。
sortquerystring選填排序欄位:marketCap(預設)、price、changePercent、volume 或 symbol。
orderquerystring選填排序方向:desc(預設)或 asc。
pagequerynumber選填頁碼,從 1 開始。
pageSizequerynumber選填每頁列數:預設 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。

參數

參數位置類型必填說明
symbolpathstring必填交易標的或指數代號,例如 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。

參數

參數位置類型必填說明
symbolpathstring必填交易標的或指數代號,例如 NWRB。比對時忽略大小寫。
rangequerystring選填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;無法解析的數值會被忽略。

參數

參數位置類型必填說明
sectorquerystring選填精確的產業名稱:Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate。
minMarketCap, maxMarketCapquerynumber選填市值上下限,單位為美元。
minPrice, maxPricequerynumber選填價格上下限,單位為美元。
minChangePercent, maxChangePercentquerynumber選填當日漲跌幅上下限,單位為百分點:-3 代表 -3%。
minVolumequerynumber選填最小日成交量,單位為股。
profitableOnlyquerystring選填設為 1 時僅保留 EPS 大於 0 的交易標的。
sortquerystring選填排序欄位:marketCap(預設)、price、changePercent、volume 或 symbol。
orderquerystring選填排序方向:desc(預設)或 asc。
pagequerynumber選填頁碼,從 1 開始。
pageSizequerynumber選填每頁列數:預設 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 狀態碼錯誤碼觸發條件
400bad_request某個參數值不被允許,例如未知的 K 線區間。
401unauthorized已設定 API_KEY,而請求沒有攜帶相符的 X-API-Key 標頭。
404not_found該代號不在資料集中。
405method_not_allowedAPI 為唯讀:/api/quotes 收到 POST 時回傳此錯誤碼。
429rate_limited同一 IP 對同一端點在 60 秒內請求超過 60 次。回應會包含以秒為單位的 Retry-After。

在產品中查看同樣的資料

市場總覽、報價頁與篩選器讀取的是和這些端點相同的資料來源。