认证方式
所有数据接口都需要在请求头中携带分配给客户的 API Key,以下两种写法任选其一:
# 推荐:Authorization Bearer
Authorization: Bearer vc_live_xxx
# 或者:X-API-Key
X-API-Key: vc_live_xxx
Key 形如 vc_live_ 加 32 位十六进制串。未携带、无效或已停用的 Key 一律返回 401 invalid_key。请勿把 Key 写进前端代码或公开仓库。
X-Request-Id,出错时响应体中的 error.request_id 与之一致。反馈问题时请附带该 ID。
端点一览
| 方法 | 路径 | 参数 | 说明 |
|---|---|---|---|
| GET | /v1/meta |
无 | 数据集概览:SKU 数、可比价 SKU 数、品牌数、类目数、最新数据日期与基础加价系数。 |
| GET | /v1/prices |
keyword brand model category page size sort |
按条件分页查询聚合后的型号价格列表,同型号多渠道报价自动合并。 |
| GET | /v1/prices/{model} |
model(路径参数) |
单个型号的详情:价格统计与全部报价。 |
| GET | /v1/trend |
model(必填)days=30(1–365) |
按日汇总的历史价格趋势:最低价、中位数、报价家数。 |
| GET | /v1/compare |
brand category keyword page size |
仅返回有多个报价来源的可比价型号,按报价家数降序。 |
| GET | /v1/catalog/brands |
limit=200(1–1000) |
品牌目录:每个品牌的型号数与价格区间。 |
| GET | /v1/catalog/categories |
limit=200(1–1000) |
类目目录:每个类目的型号数与价格区间。 |
| POST | /v1/batch |
JSON Body models:字符串数组,1–100 个 |
一次查询多个型号的详情,返回每个型号的统计与报价。 |
另有 /health(健康检查,无需认证)与 /v1/docs(本文档)两个运维/文档入口,不属于数据接口。
调用示例
先在终端中设置服务地址与 Key(把示例地址替换为实际服务地址):
export API_BASE="https://api.ibotclaw.com"
export VC_API_KEY="vc_live_xxx" # 替换为你的 API Key
下文示例统一使用 Authorization: Bearer $VC_API_KEY;也可以等价的 -H "X-API-Key: $VC_API_KEY" 代替。
01数据集概览
curl -s "$API_BASE/v1/meta" \
-H "Authorization: Bearer $VC_API_KEY"
02价格列表
curl -sG "$API_BASE/v1/prices" \
--data-urlencode "brand=美的" \
--data-urlencode "category=空调" \
-d "page=1" -d "size=20" -d "sort=price_asc" \
-H "Authorization: Bearer $VC_API_KEY"
sort 可选 price_asc(默认)、price_desc、updated_desc。返回 data 数组与 meta(page / size / total / data_date)。
03型号详情
curl -s "$API_BASE/v1/prices/KFR-35GW/N8XHC1" \
-H "Authorization: Bearer $VC_API_KEY"
型号路径参数支持包含 / 的原文;匹配时忽略大小写、空格与符号差异。没有匹配报价时返回 404 not_found。
04历史趋势
curl -sG "$API_BASE/v1/trend" \
--data-urlencode "model=KFR-35GW/N8XHC1" \
-d "days=30" \
-H "Authorization: Bearer $VC_API_KEY"
days 取值 1–365,默认 30。按 snapshot_date 升序返回每日的 lowest、median 与 supplier_count;区间内无数据时 points 为空数组,不返回 404。
05可比价型号
curl -sG "$API_BASE/v1/compare" \
--data-urlencode "brand=美的" \
--data-urlencode "category=空调" \
-d "page=1" -d "size=20" \
-H "Authorization: Bearer $VC_API_KEY"
只保留 supplier_count > 1 的型号,先按报价家数降序、再按最低价升序排列。
06品牌目录
curl -s "$API_BASE/v1/catalog/brands?limit=200" \
-H "Authorization: Bearer $VC_API_KEY"
按型号数量降序返回品牌列表,每条包含 brand、models、price_min、price_max。
07类目目录
curl -s "$API_BASE/v1/catalog/categories?limit=200" \
-H "Authorization: Bearer $VC_API_KEY"
结构与品牌目录一致,字段为 category、models、price_min、price_max。
08批量查询
curl -s -X POST "$API_BASE/v1/batch" \
-H "Authorization: Bearer $VC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"models":["KFR-35GW/N8XHC1","BCD-450WTPZM"]}'
models 最多 100 个。返回的 data 以请求中的型号字符串为键;meta 给出 requested、found 与 missing。
响应格式与错误码
成功响应统一为 {"data": ...};列表类接口另带 meta。失败响应统一为:
{
"error": {
"code": "invalid_key",
"message": "API key 无效或已停用",
"request_id": "3f9a1c0b7d2e4568"
}
}
| HTTP | code | 含义 | 处理建议 |
|---|---|---|---|
| 401 | invalid_key | 缺少、无效或已停用的 API Key。 | 检查 Authorization / X-API-Key 请求头与 Key 状态。 |
| 429 | rate_limited | 超出每秒请求数(QPS)限制。 | 按响应头 Retry-After(秒)退避后重试。 |
| 429 | quota_exceeded | 日配额或月配额已用尽。 | 等待自然日/自然月重置,或联系升级套餐。 |
| 400 | bad_request | 参数或请求体不合法,如分页超限、batch 数量越界。 | 对照参数范围修正请求。 |
| 404 | not_found | 资源不存在,如型号没有报价、路径拼写错误。 | 确认型号或路径;趋势接口无数据不会返回 404。 |
| 503 | service_unavailable | 数据库等依赖暂时不可用。 | 稍后重试;持续失败请携带 request_id 反馈。 |
| 500 | internal_error | 未预期的服务端错误。 | 稍后重试;持续失败请携带 request_id 反馈。 |
额度与限流
每个 API Key 独立计量,具体数值按客户套餐配置:
- QPS 限制:每秒请求数上限,超出立即返回
429 rate_limited,并在响应头带Retry-After: 1。 - 日配额:按自然日累计,超出返回
429 quota_exceeded,次日 0 点重置。 - 月配额:按自然月累计,超出返回
429 quota_exceeded,下月 1 日重置。 - 计量范围:通过认证的每次请求都会计入额度与用量,包括最终返回 4xx 的请求;文档与健康检查不计入。
- 用量审计:服务按 endpoint 统计调用次数与返回行数,用于对账与容量规划。
Retry-After 做指数退避,或把批量型号合并到 /v1/batch 以减少调用次数。
分页与数量上限
| 场景 | 限制 |
|---|---|
/v1/prices、/v1/compare 分页 | page ≥ 1,1 ≤ size ≤ 100,且 page × size ≤ 10000,超出返回 400 bad_request。 |
/v1/batch 型号数量 | 1–100 个;空数组或超过 100 个返回 400 bad_request。 |
/v1/catalog/brands、categories | 1 ≤ limit ≤ 1000,默认 200。 |
/v1/trend 时间窗口 | 1 ≤ days ≤ 365,默认 30。 |
深分页上限 10000 用于保护数据库。需要全量导出时,建议按品牌/类目拆分条件,或使用 /v1/batch 精准查询目标型号。
字段口径说明
price、min_price、max_price、median_price、stats.*、offers[].price、trend.points[].lowest/median、price_min/price_max 均已包含服务方基础服务系数并乘客户合约系数,四舍五入到 2 位小数,可直接对外使用,无需二次换算。
该 SKU 去重后的报价来源数量,仅数量、不含任何来源身份信息,也不是报价行数。同一来源的多行报价只计 1 次。/v1/compare 仅返回 supplier_count > 1 的型号。
/v1/meta、/v1/prices、型号详情、/v1/compare、目录与批量查询都只读取对外发布数据,被替代的历史导入不会参与聚合;趋势接口读取按天保存的发布快照。
均为数据日期,格式 YYYY-MM-DD。meta.data_date 是发布数据的最新日期;条目上的 updated_at 是该 SKU 报价的最新数据日期。
price 与 min_price 是聚合组内最低报价;max_price 为最高报价;median_price 为中位数(偶数个样本取中间两值平均)。
型号查询与批量查询会忽略大小写、空格与常见符号差异(如 -、/、括号)进行归一化匹配;响应中的 model 为该组内出现次数最多的原始写法。
每个 date 对应一个快照日:lowest 为当日最低价,median 为当日中位数,supplier_count 为当日报价来源去重数。无数据的日期不会补点。
models 为该品牌/类目下的 SKU 数量;price_min / price_max 为该范围内全部 SKU 的最低/最高价(已含基础加价与合约系数)。