ValueCube Open API

家电价格数据 APIv1

全渠道报价聚合、历史价格趋势、品牌与类目目录、批量型号查询。全部接口返回 JSON,价格已包含基础加价系数并按客户合约系数换算。

Base URL https://api.ibotclaw.com 认证 Bearer / X-API-Key 更新频率 每日 字符集 UTF-8

认证方式

所有数据接口都需要在请求头中携带分配给客户的 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 写进前端代码或公开仓库。

i 响应头会返回 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数据集概览

GET/v1/meta
curl -s "$API_BASE/v1/meta" \
  -H "Authorization: Bearer $VC_API_KEY"

02价格列表

GET/v1/prices
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型号详情

GET/v1/prices/{model}
curl -s "$API_BASE/v1/prices/KFR-35GW/N8XHC1" \
  -H "Authorization: Bearer $VC_API_KEY"

型号路径参数支持包含 / 的原文;匹配时忽略大小写、空格与符号差异。没有匹配报价时返回 404 not_found。

04历史趋势

GET/v1/trend
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可比价型号

GET/v1/compare
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品牌目录

GET/v1/catalog/brands
curl -s "$API_BASE/v1/catalog/brands?limit=200" \
  -H "Authorization: Bearer $VC_API_KEY"

按型号数量降序返回品牌列表,每条包含 brand、models、price_min、price_max。

07类目目录

GET/v1/catalog/categories
curl -s "$API_BASE/v1/catalog/categories?limit=200" \
  -H "Authorization: Bearer $VC_API_KEY"

结构与品牌目录一致,字段为 category、models、price_min、price_max。

08批量查询

POST/v1/batch
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"
  }
}
HTTPcode含义处理建议
401invalid_key缺少、无效或已停用的 API Key。检查 Authorization / X-API-Key 请求头与 Key 状态。
429rate_limited超出每秒请求数(QPS)限制。按响应头 Retry-After(秒)退避后重试。
429quota_exceeded日配额或月配额已用尽。等待自然日/自然月重置,或联系升级套餐。
400bad_request参数或请求体不合法,如分页超限、batch 数量越界。对照参数范围修正请求。
404not_found资源不存在,如型号没有报价、路径拼写错误。确认型号或路径;趋势接口无数据不会返回 404。
503service_unavailable数据库等依赖暂时不可用。稍后重试;持续失败请携带 request_id 反馈。
500internal_error未预期的服务端错误。稍后重试;持续失败请携带 request_id 反馈。

额度与限流

每个 API Key 独立计量,具体数值按客户套餐配置:

! 收到 429 时不要原地高频重试。请读取 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、categories1 ≤ limit ≤ 1000,默认 200。
/v1/trend 时间窗口1 ≤ days ≤ 365,默认 30。

深分页上限 10000 用于保护数据库。需要全量导出时,建议按品牌/类目拆分条件,或使用 /v1/batch 精准查询目标型号。

字段口径说明

i 本 API 只提供聚合后的市场价格,不含任何供应商身份信息。所有价格已包含服务方的基础服务系数,客户侧另按合约系数结算。
价格已含基础加价与合约系数

price、min_price、max_price、median_price、stats.*、offers[].price、trend.points[].lowest/median、price_min/price_max 均已包含服务方基础服务系数并乘客户合约系数,四舍五入到 2 位小数,可直接对外使用,无需二次换算。

supplier_count

该 SKU 去重后的报价来源数量,仅数量、不含任何来源身份信息,也不是报价行数。同一来源的多行报价只计 1 次。/v1/compare 仅返回 supplier_count > 1 的型号。

发布数据口径

/v1/meta、/v1/prices、型号详情、/v1/compare、目录与批量查询都只读取对外发布数据,被替代的历史导入不会参与聚合;趋势接口读取按天保存的发布快照。

updated_at / data_date

均为数据日期,格式 YYYY-MM-DD。meta.data_date 是发布数据的最新日期;条目上的 updated_at 是该 SKU 报价的最新数据日期。

price / min_price / median_price

price 与 min_price 是聚合组内最低报价;max_price 为最高报价;median_price 为中位数(偶数个样本取中间两值平均)。

model 匹配

型号查询与批量查询会忽略大小写、空格与常见符号差异(如 -、/、括号)进行归一化匹配;响应中的 model 为该组内出现次数最多的原始写法。

trend 趋势点

每个 date 对应一个快照日:lowest 为当日最低价,median 为当日中位数,supplier_count 为当日报价来源去重数。无数据的日期不会补点。

catalog models

models 为该品牌/类目下的 SKU 数量;price_min / price_max 为该范围内全部 SKU 的最低/最高价(已含基础加价与合约系数)。