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。下方所有筛选条件在此同样适用;无法解析的取值会被忽略。
参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 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。 |