二手车价格评估 API：为什么返回的是区间，两个价格分别怎么用

做二手车业务时最容易被用户追问的一句话是「你们这个价格准不准」。如果接口吐出一个孤零零的数字，用户一定会当成报价：给低了他觉得你在压价，给高了后续验车又要往回调，投诉基本从这里开始。真实交易里本来就有议价空间——同一辆车，急着出手时是一个价，挂在店里慢慢卖又是另一个价。

• api.xujian.tech
• V：xujian_cq

usedcar.price 的设计就顺着这个现实走：传品牌型号 + 车龄 + 里程 + 车况 + 地域，返回的是 priceStart / priceEnd 两个值组成的价格区间（单位：万元），而不是一口价。一次 POST 就能把「多少参数能估出价」这件事收敛掉。

接口速览

一、两个价格分别怎么用

页面上的常见写法是取中值做主展示、把区间放在副标题：「约 13.6 万（12.5 万 ~ 14.8 万）」。这样既给出了明确感知，又保留区间应有的不确定性。反过来切忌只展示 priceEnd 并称之为「评估价」——那是区间的乐观端，被当成承诺价最容易出纠纷。

二、哪些场景用得上

三、请求参数

3.1 请求头

3.2 JSON 请求体字段

全部可选，但 brand 与 model 至少填一个，单个字段 ≤ 50 字符。

参数重要度排序：mileage（权重最高）> registrationDate / year（车龄折旧）> location（地域差）> accidentHistory（车况）。这四五个字段务必让用户填准，其余字段是可选项，但填得越全结果越稳。

四、返回字段与调用示例

4.1 顶层结构与业务字段

data 内部：

4.2 curl

curl -s -X POST "https://api.xujian.tech/openapi/usedcar/price" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的APIKey" \
  -d '{
    "brand": "大众",
    "model": "迈腾",
    "year": "2023",
    "configuration": "330TSI DSG 豪华型",
    "registrationDate": "2022-03",
    "mileage": "8.5",
    "accidentHistory": "0",
    "transferCount": "0",
    "maintenanceRecord": "全程4S店保养",
    "fuelType": "汽油",
    "transmissionType": "自动",
    "displacement": "2.0",
    "color": "黑色",
    "location": "北京",
    "description": "车辆外观完好，内饰9成新，无任何改装"
  }'

4.3 成功响应

{
   
  "code": 0,
  "msg": "success",
  "data": {
   
    "priceStart": 12.5,
    "priceEnd": 14.8,
    "tip": "估计信息来源网络内容，仅供参考",
    "apiCode": "usedcar.price",
    "apiName": "二手车价格评估",
    "chargeType": "PER_CALL",
    "balance": 99.5000,
    "costMs": 1200
  }
}

4.4 Python：给表单做个估价函数

import requests

API_URL = "https://api.xujian.tech/openapi/usedcar/price"


def estimate_price(car: dict) -> tuple[float, float] | None:
    """评估二手车价格区间（万元）；估不出返回 None 且不扣费"""
    try:
        resp = requests.post(
            API_URL,
            json=car,
            headers={
   "Content-Type": "application/json", "X-API-Key": API_KEY},
            timeout=30,
        )
        result = resp.json()
    except Exception as e:
        print(f"请求异常：{e}")
        return None
    if result.get("code") != 0:
        print(f"评估失败（不收费）：{result.get('msg')}")
        return None
    data = result["data"]
    return data["priceStart"], data["priceEnd"]


def render(start: float, end: float) -> str:
    """页面展示：中值主标题 + 区间副标题"""
    mid = round((start + end) / 2, 2)
    return f"约 {mid} 万（{start} 万 ~ {end} 万，估计信息来源网络内容，仅供参考）"


if __name__ == "__main__":
    car = {
   
        "brand": "大众", "model": "迈腾", "year": "2023",
        "registrationDate": "2022-03", "mileage": "8.5",
        "accidentHistory": "0", "transferCount": "0",
        "fuelType": "汽油", "transmissionType": "自动",
        "displacement": "2.0", "color": "黑色", "location": "北京",
    }
    res = estimate_price(car)
    if res:
        print(render(*res))

4.5 Java（Hutool）

JSONObject req = JSONUtil.createObj()
        .set("brand", "大众")
        .set("model", "迈腾")
        .set("year", "2023")
        .set("configuration", "330TSI DSG 豪华型")
        .set("registrationDate", "2022-03")
        .set("mileage", "8.5")
        .set("accidentHistory", "0")
        .set("transferCount", "0")
        .set("fuelType", "汽油")
        .set("transmissionType", "自动")
        .set("displacement", "2.0")
        .set("color", "黑色")
        .set("location", "北京");

String body = HttpRequest.post("https://api.xujian.tech/openapi/usedcar/price")
        .header("Content-Type", "application/json")
        .header("X-API-Key", apiKey)
        .timeout(20000)
        .body(req.toString())
        .execute()
        .body();

JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
   
    System.out.println("评估失败（不收费）：" + json.getStr("msg"));
    return;
}
JSONObject data = json.getJSONObject("data");
System.out.printf("评估区间：%.2f 万 ~ %.2f 万%n",
        data.getDouble("priceStart"), data.getDouble("priceEnd"));

4.6 JavaScript（浏览器 / Node 18+）

const resp = await fetch("https://api.xujian.tech/openapi/usedcar/price", {
   
  method: "POST",
  headers: {
    "Content-Type": "application/json", "X-API-Key": API_KEY },
  body: JSON.stringify({
   
    brand: "大众", model: "迈腾", year: "2023",
    registrationDate: "2022-03", mileage: "8.5",
    accidentHistory: "0", location: "北京",
  }),
});

const {
    code, msg, data } = await resp.json();
if (code === 0) {
   
  console.log(`评估区间：${
     data.priceStart} 万 ~ ${
     data.priceEnd} 万`);
  console.log(`免责说明：${
     data.tip}`);
} else {
   
  console.warn("评估失败（不收费）：", msg);
}

五、错误码与不计费说明

不计费场景汇总：brand 与 model 都为空、单字段超过 50 字符、服务未启用、估不出价格区间、上游超时或网络异常、鉴权失败、余额不足。

六、接入建议

1. mileage 传万公里 + registrationDate 传 YYYY-MM：这两个字段对结果影响最大，前端要做单位提示（用户很容易填成「8.5 万公里」或「85000」这种带单位的总里程）。
2. 失败一定要落到「人工估价」而不是报错：「估不出价格」这条返回本身不收费，说明这类车的参数没覆盖到，正好可以做成收集线索的入口。
3. tip 原样展示：接口的免责说明是产品合规的一部分，别自作主张删掉或改写。
4. 加缓存，别让同一次表单提交重复扣费：按「品牌 + 型号 + 上牌 + 里程 + 城市」拼 key 缓存几小时，用户在页面上反复改一个颜色不会再产生 0.5 元。
5. 估值和车源列表搭配用：先用按次 0.01 元的车源列表接口把车源拉下来，再对缺价的车源跑估值，比把整个库都估一遍便宜得多。