跳到主要内容

API 参考

API 文档

这是一个只读的 JSON API,与本站页面使用同一份行情数据。成功响应使用 { data, meta } 封装;失败响应使用 { error: { code, message } }。

基础 URL
http://localhost:3000
方法
仅支持 GET
格式
JSON、UTF-8
限流
每个 IP、每个接口在 60 秒内最多 60 次请求

以下是 API 示例,本站仅提供静态展示。

演示
除非服务端同时设置 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。

在产品中查看同样的数据

市场总览、报价页与筛选器读取的是和这些接口相同的数据源。