二手车信息查询 API（车型+车况+首付，一次拉取批量车源）· usedcar.list 接口文档

Q: 可以按品牌或价格筛选车源吗？

当前上游按批次返回车源列表，不支持条件筛选；如需筛选请拉取后在本地做过滤，并用 limit 控制单次返回量。

Q: 没有返回车源会扣费吗？

不会。接口采用「先预鉴权、拿到车源后再扣费」的两段式流程，一次都没查到时返回失败且不扣费。

Q: 为什么没有返回车辆 ID？

上游的 dataId / dId / cid 属于数据源内部主键，跨批次不稳定，对外不返回；建议用「车型名称 + 注册年份 + 行驶里程」组合作为去重键。

接口概述

一句话说明

usedcar.list 是拉取成批车源最省事的接口：不需要任何查询条件，一次请求返回多条车源，字段精简到可直接入库或渲染列表页。如需对某辆车做价格判断，请配合使用 usedcar.price（二手车价格评估）。

接口规格
请求地址	`https://api.xujian.tech/openapi/usedcar/list`
请求方式	GET（`limit` 放 Query String，可省略）
鉴权方式	请求头 `X-API-Key`
接口编码	`usedcar.list`
收费类型	PER_CALL（按次计费，0.0100 元/次）
计费特殊规则	查得计费：上游不可用或一条车源都没有时返回失败且不扣费
响应格式	JSON，`Content-Type: application/json;charset=UTF-8`
是否需要授权	否（无需授权，API Key 有效且余额充足即可调用）
最多返回	50 条（可用 `limit` 收敛）
典型用途	车源同步、行情分析、选品、展厅小程序 / H5 展示

快速开始

cURL

curl -s "https://api.xujian.tech/openapi/usedcar/list" \
  -H "X-API-Key: 你的APIKey"

单位约定

mileage（行驶里程）单位是万公里； downPayment（首付价格）单位是万元； regDate（注册年份）形如「2024年」。渲染前请注意带上单位。

请求参数

请求头（Header）
参数名	类型	必填	说明
`X-API-Key`	String	是	开发者 API Key

业务参数（Query String，全部可选）
参数名	类型	必填	示例	说明
`limit`	Integer	否	10	期望返回条数；实际返回取 `limit` 与系统上限（50）的较小值，留空或 ≤0 时取上限

响应参数

data 字段
字段	类型	说明
`total`	int	本次返回的车源条数
`list`	Array	车源数组；字段见下表
`apiCode`	String	接口编码 `usedcar.list`
`apiName`	String	接口名称
`chargeType`	String	计费类型
`balance`	BigDecimal	调用完成后（已扣费）的账户余额（元）
`costMs`	Long	本次调用耗时（毫秒）

list[] 车源字段

字段	类型	示例	说明
`carName`	String	长安启源E07 2025款纯电两驱 90kWh Max智驾版	车型名称（含品牌、年款与配置）
`imageUrl`	String	https://……/car.jpg	车辆图片链接，可直接用于 `<img>`
`mileage`	String	1.2万公里	行驶里程（万公里）
`regDate`	String	2024年	车辆注册年份
`downPayment`	String	8.42万	首付价格（万元）
`tags`	Array	["新上架","0次过户","原厂质保"]	车辆标签：新上架 / 准新车 / 0次过户 / 原厂质保 / 个人一手车 / 7天无理由退车等

响应示例

成功（code = 0）

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "list": [
      {
        "carName": "长安启源E07 2025款 纯电 两驱 90kWh Max智驾版",
        "imageUrl": "https://cdn.example.com/car/e07.jpg",
        "mileage": "1.2万公里",
        "regDate": "2024年",
        "downPayment": "8.42万",
        "tags": ["新上架", "0次过户", "原厂质保"]
      }
    ],
    "apiCode": "usedcar.list",
    "apiName": "二手车信息查询",
    "chargeType": "PER_CALL",
    "balance": 99.9900,
    "costMs": 380
  }
}

失败（无车源）—— 不收费

JSON

{
  "code": 500,
  "msg": "未查询到可用车源，请稍后重试；本次调用不计费",
  "data": null
}

错误码与常见失败原因

code	msg（示例）	处理建议
0	success	调用成功
500	缺少请求头 X-API-Key	补充 X-API-Key
500	API Key 无效 / API Key 已停用	检查 Key 或重新启用
500	客户不存在或已停用	联系平台（可联系微信xujian_cq）
500	接口不存在或已停用	确认 usedcar.list 当前是否维护中
500	余额不足，请先充值。可联系微信xujian_cq	充值后重试，余额不足不扣费
500	二手车服务未启用 / 二手车服务未配置（上游凭证缺失）	平台侧配置问题，联系平台处理；不计费
500	未查询到可用车源，请稍后重试；本次调用不计费	稍后重试；不计费
500	数据服务暂时不可用（请求上游超时或网络异常），本次调用不计费	稍后重试；不计费

多语言代码示例

Java（Hutool）

Java

String body = HttpRequest.get("https://api.xujian.tech/openapi/usedcar/list")
        .form("limit", "20")
        .header("X-API-Key", apiKey)
        .timeout(15000)
        .execute()
        .body();

JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
    System.out.println("查询失败（不收费）：" + json.getStr("msg"));
    return;
}
JSONArray list = json.getJSONObject("data").getJSONArray("list");
for (int i = 0; i < list.size(); i++) {
    JSONObject car = list.getJSONObject(i);
    System.out.printf("%s | 首付 %s | 里程 %s%n",
            car.getStr("carName"), car.getStr("downPayment"), car.getStr("mileage"));
}

Python

import requests


def list_used_cars(api_key: str, limit: int = 20):
    """拉取二手车车源；无车源返回空列表且不扣费"""
    resp = requests.get(
        "https://api.xujian.tech/openapi/usedcar/list",
        params={"limit": limit},
        headers={"X-API-Key": api_key},
        timeout=20,
    )
    result = resp.json()
    if result.get("code") != 0:
        print("查询失败（不收费）：", result.get("msg"))
        return []
    return result["data"]["list"]


if __name__ == "__main__":
    for car in list_used_cars("你的APIKey"):
        print(car["carName"], car["downPayment"], car["mileage"], car["tags"])

JavaScript（浏览器 / Node 18+）

JavaScript

const resp = await fetch("https://api.xujian.tech/openapi/usedcar/list?limit=20", {
  headers: { "X-API-Key": API_KEY },
});

const { code, msg, data } = await resp.json();
if (code === 0) {
  data.list.forEach((car) => console.log(car.carName, car.downPayment, car.tags.join("/")));
} else {
  console.warn("查询失败（不收费）：", msg);
}

常见问题（FAQ）

usedcar.list 接口怎么收费？

usedcar.list 的收费类型为 PER_CALL（按次计费），当前单价 0.0100 元/次，调用前校验余额，余额不足返回「余额不足，请先充值。可联系微信xujian_cq」且不扣费；充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。

可以按品牌或价格筛选吗？

当前上游按批次返回车源列表，不支持条件筛选。如需筛选请拉取后在本地做过滤，并用 limit 控制单次返回量。

没有返回车源会扣费吗？

不会。接口采用「先预鉴权、拿到车源后再扣费」的两段式流程，一条都没查到时返回失败且不扣费、不写扣费流水。

为什么没有返回车辆 ID？

上游的 dataId / dId / cid 属数据源内部主键，跨批次不稳定也不可解读，因此不返回。去重建议用「carName + regDate + mileage」组合键。

想给某辆车估价怎么办？

本接口返回的车源字段里没有估价结果；请调用 usedcar.price（二手车价格评估），提交品牌、型号、上牌时间、行驶里程等参数即可得到价格区间。

调用需要签名或加密吗？

不需要。XAPI 的接口仅校验请求头 X-API-Key，不做签名、时间戳或加密。

二手车信息查询 API（usedcar.list）