二手车车源查询 API：一个 `limit` 参数拉回最新在售车源列表

做二手车行情分析、车源聚合展示、选品比价，第一步都是拿数据：当前有哪些车源在售、车型是什么、跑了多少公里、哪年上牌、首付多少、挂了什么标签。自己去各个平台爬，既不稳定也不合规；用人工整理，数据三天就过期。usedcar.list 把这件事做成一个 GET 接口：不传业务参数也能调，只用一个可选的 limit 控制条数，返回结构化的车源列表。

计费口径：没有车源时不收费 。当前拉不到车源时返回失败（JSON 的 code != 0 分支），不扣费、不写扣费流水、不累加调用次数。详见第九节。

api.xujian.tech
V：xujian_cq

接口速览

关键事实	说明
接口地址	`https://api.xujian.tech/openapi/usedcar/list`
接口编码	`usedcar.list`
请求方式	GET
鉴权方式	请求头 `X-API-Key`，不做签名、时间戳或加密
请求参数	`limit`（可选，期望条数）
返回条数	不传或小于等于 0 时取上限（当前 50 条），传值超过上限也只会返回上限条数
计价	按次计费，0.01 元/次
不计费场景	服务未启用或未配置、鉴权失败、余额不足、未查询到可用车源
建议超时	15 秒以上（`costMs` 为真实耗时）

一、返回的车源字段够做什么

一条车源只有六个字段，但组合起来能覆盖不少场景：

字段	能做什么
`carName`	车型全称（含年款、配置），做型号归并与价格对比的主键
`imageUrl`	直接用于列表页展示（注意防盗链与缓存策略）
`mileage`	行驶里程，做车况分层与折旧估算
`regDate`	注册年份，与当前年份相减即车龄
`downPayment`	首付价格，金融方案展示、分期试算的起点
`tags`	「新上架」「准新车」「0次过户」「原厂质保」等，用于打标与筛选

典型用法：

场景	组合方式
车源聚合列表页	六字段直接渲染，`imageUrl` 做封面，`tags` 做角标
行情分析	按 `carName` 归并车型，用 `mileage` + `regDate` 做折旧曲线
选品参考	看某车型在售车源数量与 `downPayment` 区间
分期试算入口	用 `downPayment` 作为首付默认值
定时同步任务	每天拉一次全量，与本地库做差量更新

接口刻意不返回上游的数据主键（dataId / dId / cid 之类），因为这些是平台内部标识、稳定性不可控。需要唯一键时建议用 carName + regDate + mileage 组合做业务主键。

二、请求参数

参数名	位置	必填	类型	示例	说明
`X-API-Key`	Header	是	String	---	开发者 API Key
`limit`	Query	否	Integer	20	期望返回条数；为空或 ≤ 0 取上限；超过上限按上限返回

三、返回字段

3.1 顶层字段

字段	类型	说明
`code`	int	`0` 成功，非 0 失败（统一 `500`）
`msg`	String	成功 `success`，失败为具体原因
`data.total`	Integer	本次返回的车源条数
`data.list`	Array	车源列表
`data.apiCode`	String	`usedcar.list`
`data.apiName`	String	二手车信息查询
`data.chargeType`	String	`PER_CALL`
`data.balance`	BigDecimal	扣费后余额（元）
`data.costMs`	Long	本次调用耗时（毫秒）

3.2 list\[\] 字段

字段	类型	示例	说明
`carName`	String	长安启源E07 2025款纯电两驱 90kWh Max智驾版	车型名称（含年款与配置）
`imageUrl`	String	https://....../xxx.jpg	车辆图片链接
`mileage`	String	2.1万公里	行驶里程，单位万公里
`regDate`	String	2024年	车辆注册年份
`downPayment`	String	5.8万	首付价格，单位万元
`tags`	Array	$"新上架", "准新车", "0次过户"$	车辆标签数组

里程与首付是带单位的字符串（「2.1万公里」「5.8万」），参与计算前要剥离单位；注册年份是「2024年」这种形式，算车龄时取年份部分即可。

四、调用示例

4.1 curl

bash 复制代码

curl -s -G "https://api.xujian.tech/openapi/usedcar/list" \
  --data-urlencode "limit=20" \
  -H "X-API-Key: 你的APIKey"

4.2 Java

java 复制代码

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.xujian.tech/openapi/usedcar/list?limit=20"))
        .header("X-API-Key", apiKey)
        .timeout(Duration.ofSeconds(15))
        .GET()
        .build();

String json = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8))
        .body();

4.3 Python

python 复制代码

import requests


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

4.4 JavaScript

javascript 复制代码

const { code, msg, data } = await fetch(
  "https://api.xujian.tech/openapi/usedcar/list?limit=20",
  { headers: { "X-API-Key": API_KEY } }
).then((r) => r.json());

if (code === 0) {
  data.list.forEach((c) => console.log(c.carName, c.mileage, c.regDate, c.downPayment));
} else {
  console.warn("查询失败（不收费）：", msg);
}

五、返回示例

json 复制代码

{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 3,
    "list": [
      {
        "carName": "长安启源E07 2025款 纯电 两驱 90kWh Max智驾版",
        "imageUrl": "https://example.com/car/xxx.jpg",
        "mileage": "2.1万公里",
        "regDate": "2024年",
        "downPayment": "5.8万",
        "tags": ["新上架", "准新车", "0次过户"]
      },
      {
        "carName": "大众迈腾 2022款 330TSI DSG 豪华型",
        "imageUrl": "https://example.com/car/yyy.jpg",
        "mileage": "4.6万公里",
        "regDate": "2022年",
        "downPayment": "6.2万",
        "tags": ["个人一手", "全程4S店保养"]
      },
      {
        "carName": "丰田凯美瑞 2021款 2.5G 豪华版",
        "imageUrl": "https://example.com/car/zzz.jpg",
        "mileage": "7.3万公里",
        "regDate": "2021年",
        "downPayment": "5.1万",
        "tags": ["0次过户", "原厂质保"]
      }
    ],
    "apiCode": "usedcar.list",
    "apiName": "二手车信息查询",
    "chargeType": "PER_CALL",
    "balance": 99.9900,
    "costMs": 780
  }
}

无车源时（不计费）：

json 复制代码

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

六、落地实践

6.1 车型归并 + 车龄计算

python 复制代码

import re
from datetime import date


def parse_car(car: dict) -> dict:
    """把带单位的字符串解析成可用数值"""
    def number(text: str, unit: str) -> float | None:
        if not text:
            return None
        cleaned = text.replace(unit, "").strip()
        try:
            return float(cleaned)
        except ValueError:
            return None

    year_match = re.search(r"(\d{4})", car.get("regDate") or "")
    return {
        "车型": car.get("carName"),
        "里程(万公里)": number(car.get("mileage", ""), "万公里"),
        "车龄": date.today().year - int(year_match.group(1)) if year_match else None,
        "首付(万元)": number(car.get("downPayment", ""), "万"),
        "标签": car.get("tags") or [],
    }

6.2 每日定时同步（差量更新）

java 复制代码

/**
 * 与本地库做差量同步：以 carName + regDate + mileage 组合作为业务主键
 */
public SyncResult sync(List<UsedCarRow> remote, Set<String> existedKeys) {
    int added = 0;
    List<UsedCarRow> toInsert = new ArrayList<>();
    for (UsedCarRow row : remote) {
        String key = row.getCarName() + "|" + row.getRegDate() + "|" + row.getMileage();
        if (!existedKeys.contains(key)) {
            toInsert.add(row);
            added++;
        }
    }
    return new SyncResult(remote.size(), added);
}

6.3 列表页渲染的三个注意点

图片要代理或缓存 ：imageUrl 是源站地址，直接 <img src> 可能受防盗链影响，建议服务端中转或 CDN 缓存。
字符串字段别直接排序 ：mileage 是「2.1万公里」这种格式，按字符串排会把「10万公里」排到「2.1万公里」前面，排序前先转数值。
tags 是数组且可能为空 ：渲染角标前先判空，别直接 tags[0]。

七、实践建议

limit 不用传也能调：不传就是拉满上限，适合做每日全量同步。
结果缓存 6 ~ 12 小时：车源不会分钟级变化，缓存能省掉绝大部分调用。
无车源 = 失败分支（code ≠ 0）：这是"暂时没数据"，不扣费，按空结果处理即可，不要重试轰炸。
不要指望它做唯一性判重：没有返回主键，用三字段组合键。
需要价格区间时搭配 usedcar.price：车源列表不含标价估值，只有首付参考；要估价请用价格评估接口。
单位要统一：里程与首付都带单位字符串，入库前清洗成数值字段，查询和排序才不会出错。

八、错误码与排查

code	msg（示例）	处理建议
0	success	调用成功
500	缺少请求头 X-API-Key / API Key 无效 / 已停用	检查请求头与 Key 状态
500	余额不足，请先充值	充值后重试，余额不足不扣费
500	二手车服务未启用 / 未配置	稍后重试；不计费
500	未查询到可用车源，请稍后重试；本次调用不计费	稍后重试或直接走空结果分支；不计费

九、计费与接入

项目	说明
单价	0.01 元/次
计费方式	按次计费，调用前校验余额，返回至少一条车源才计一次
不计费场景	服务未启用或未配置、鉴权失败、余额不足、无可用车源
建议超时	15 秒以上

接入流程：注册开发者账号 → 控制台创建 API Key → 请求头带上 X-API-Key 即可调用，无需签名或加密。控制台可查看调用量、扣费流水与余额。

服务站点：api.xujian.tech（纯文本域名，不做跳转）。接口试用、数据与充值咨询可在控制台提交工单，或联系 Vxujian_cq。
边界说明：本接口返回的是平台可查的车源快照，价格类字段（首付）随上游策略变动，仅作参考；实际成交请以车商报价与合同为准。

十、小结

车源列表这类接口的价值在于"省心"：一个可选参数、六个字段、单价一分钱，够做同步、够做展示、够做粗略行情。真正要花心思的不是调用，而是把带单位的字符串清洗干净 以及设计一个稳定的业务主键。

使用时要记住：

limit 是可选的上限控制，不传就拉满；
里程与首付带单位，排序前必须转数值；
没有主键返回，用 carName + regDate + mileage 组合去重；
无车源走失败分支且不扣费；
每日一次全量 + 本地差量，比高频轮询划算得多。

配套接口：usedcar.price（0.50 元/次）按车型参数评估价格区间；想做完整的收车评估链路，可以用列表接口选品、再用评估接口定价。

二手车车源查询 API：一个 `limit` 参数拉回最新在售车源列表