POE

POE Currency Watch — API 文档

poecurrency.top · 流放之路国服通货价格数据接口

← 返回看板

目录

GET /api/summary

通货均价汇总。缓存 1 小时，响应头 X-Cache: HIT/MISS。

GET /api/summary

参数

参数类型说明
version可选"1" = POE1，"2" = POE2。默认 1
season可选历史赛季标识如 mirage。不传默认使用当前赛季（season.json 中列表第一项）
赛季规则：不携带 season 参数时，PLATFORM 自动返回当前赛季数据（即 seasons.json 中各版本列表的第一项）。携带 season 参数为历史数据查询，仅当该赛季被归档（新赛季开启后旧赛季数据迁移）时才可查询到数据。
若只需始终获取当前赛季数据，不要携带 season。仅在需要查询历史数据时才使用此参数。

示例

curl https://poecurrency.top/api/summary
curl "https://poecurrency.top/api/summary?version=2"
curl "https://poecurrency.top/api/summary?version=1&season=mirage"

响应

按通货类型分组的 JSON 数组，每项包含 items 列表：

字段类型说明
category_labelstring类型名（通货、圣甲虫、文身…）
item_namestring物品名称（中文）
engnamestring物品英文名
buy_avgfloat64今日买1均价
sell_avgfloat64今日卖均价（sell1~5 去极值平均）
buy_avg_yesterdayfloat64昨日买1均价
sell_avg_yesterdayfloat64昨日卖均价
buy_avg_ratiofloat64买涨跌 (%)
sell_avg_ratiofloat64卖涨跌 (%)
latest_buy1float64最新买1实时价
latest_sell1float64最新卖1实时价
latest_datetimestring最新数据时间（东八区）
prev_buy1float64倒数第二笔买1
prev_buy1_datetimestring倒数第二笔对应时间
errorbool数据异常标记
error_infostring异常说明
currency_unitstring计价单位：c/e/d

GET /api/summary_validate 需要 Token 新增

与 /api/summary 返回结构相同，但必须在请求中携带有效 API Token。 在计算买均价 / 卖均价之前，会对 buy1 和 sell1 的时间序列进行异常检测并剔除异常数据点。

Token 鉴权：通过 ?token= 查询参数或 X-API-Token 请求头传递。无效 token 返回 HTTP 401。
GET /api/summary_validate

参数

参数类型说明
token必填API Token
version可选"1" = POE1，"2" = POE2
season可选历史赛季标识（同 /api/summary）

额外字段

字段类型说明
anomaly_countint被剔除的异常数据点数量

示例

curl "https://poecurrency.top/api/summary_validate?token=YOUR_TOKEN&version=2"

GET /api/db/price

查询通货历史价格记录。无 token 时自动限制查询范围为最近 24 小时。

GET /api/db/price

参数

参数类型说明
item_name可选物品名称
category_label可选类型名称
hours可选查询最近 N 小时（无 token 时 ≤24）
start可选开始时间 "2006-01-02 15:04:05"
end可选结束时间
currency_unit可选过滤计价单位
limit可选返回条数（默认 100，最大 10000）
order可选ASC / DESC（默认 DESC）
version可选POE 版本
season可选历史赛季标识。不传使用当前赛季
token可选API Token（携带后解除 24h 限制）

示例

# 查询神圣石最近 48 小时价格（需要 token）
curl "https://poecurrency.top/api/db/price?item_name=神圣石&category_label=通货&hours=48&token=YOUR_TOKEN"

# 无 token 时最多查 24 小时
curl "https://poecurrency.top/api/db/price?item_name=神圣石&category_label=通货"

响应

返回 JSON 数组，每行包含：category_label、item_name、engname、datetime、buy1~buy5、sell1~sell5、currency_unit 等所有 price_data 表字段。

GET /api/db/price_validate 需要 Token 新增

与 /api/db/price 相同但必须携带有效 Token，且不限时间范围。 返回前会对 buy1 / sell1 时间序列做异常检测，剔除异常数据行。

GET /api/db/price_validate

参数

与 /api/db/price 相同，但 token 为必填，且无 24h 限制。

示例

curl "https://poecurrency.top/api/db/price_validate?item_name=神圣石&category_label=通货&hours=168&token=YOUR_TOKEN"

GET /api/db/items

统一分页接口，返回通货卡片数据 + hot_tags。

GET /api/db/items

参数

参数类型说明
page必填页码，从 1 开始
limit可选每页条数（默认 10~动态）
category_label可选筛选类型
filter可选hot / abnormal
search可选搜索关键词
sort_by可选排序列
sort_order可选ASC / DESC
item_names可选逗号分隔的物品名列表（策略模式）
version可选POE 版本
season可选历史赛季标识。不传使用当前赛季

响应

字段类型说明
itemsarray卡片数据数组
totalint总条数
pageint当前页码
total_pagesint总页数
hot_tagsarray热门物品标签数组

GET /api/db/currencies

获取通货类型及子项目列表。

GET /api/db/currencies

参数

参数类型说明
version可选POE 版本
season可选历史赛季标识。不传使用当前赛季

GET /api/db/latest

获取指定物品的最新一条价格记录。

GET /api/db/latest

参数

参数类型说明
category_label必填类型名称
item_name必填物品名称
version可选POE 版本
season可选历史赛季标识。不传使用当前赛季
token可选API Token（解除 24h 限制）

GET /api/overlay

获取通货计价覆盖表（哪些通货用神圣石 d 计价）。

GET /api/overlay

参数

参数类型说明
version可选POE 版本
season可选历史赛季标识。不传使用当前赛季

GET /api/season_list

获取赛季列表。

GET /api/season_list

参数

参数类型说明
version可选poe1 或 poe2，不传返回全部

示例

# 返回全部版本的所有赛季
curl https://poecurrency.top/api/season_list

# 只返回 POE1 的赛季列表
curl "https://poecurrency.top/api/season_list?version=poe1"

# 只返回 POE2 的赛季列表
curl "https://poecurrency.top/api/season_list?version=poe2"

响应

指定 version 时返回赛季名称字符串数组，不传 version 时返回按版本分组的对象：

// version=poe1
["mirage"]

// version=poe2
["RunesOfAldur"]

// 不传 version
{
  "poe1": ["mirage"],
  "poe2": ["RunesOfAldur"]
}

GET /api/check-token 新增

校验 API Token 是否有效（未过期）。无需认证即可调用。

⏱ 限流：同一 IP 每小时最多请求 10 次，防止暴力破解。超限返回 "message": "请求过于频繁"。

GET /api/check-token

参数

参数类型说明
token必填API Token，也可通过 X-API-Token 请求头传递

响应

字段类型说明
validbooleanToken 是否有效（未过期）
usernamestringToken 所属用户名
expires_atstring过期时间（东八区）
messagestring状态描述（"Token 有效" / "Token 已过期" 等）

示例

# 通过 URL 参数
curl "https://poecurrency.top/api/check-token?token=YOUR_TOKEN"

# 通过请求头
curl -H "X-API-Token: YOUR_TOKEN" https://poecurrency.top/api/check-token

有效 Token 的响应

{
  "valid": true,
  "username": "free_user",
  "expires_at": "2026-07-29 12:00:00",
  "message": "Token 有效"
}

已过期 Token 的响应

{
  "valid": false,
  "username": "free_user",
  "expires_at": "2026-06-01 12:00:00",
  "message": "Token 已过期"
}

计算方式说明

buy_avg（今日买1均价）

取今日所有 buy1 值的简单算术平均。

sell_avg（今日卖均价）

每笔数据的 sell1~sell5（5 档卖出价）先去掉最大值和最小值（trimmed mean），得到该笔的卖均价；再对当天所有笔的卖均价求简单平均。

buy_avg_yesterday / sell_avg_yesterday

同上，使用昨日数据。

buy_avg_ratio / sell_avg_ratio（涨跌百分比）

((今日均价 - 昨日均价) / 昨日均价) × 100，保留两位小数。

latest_buy1 / latest_sell1

最新一条数据的 buy1 / sell1。

error / error_info（数据异常标记）

currency_unit（计价单位）

POE1 默认 c（混沌石），POE2 默认 e（崇高石）。高价值通货通过 overlay 表覆盖为 d（神圣石）。

认证说明

认证方式参数位置示例
URL 参数 ?token= /api/db/price_validate?token=abc123
请求头 X-API-Token curl -H "X-API-Token: abc123" /api/db/price_validate