车辆、能源与地理数据 API 实战：把定价、油价、行政区划串成一条链路

二手车、物流、加油站、本地生活这些业务，背后都依赖三类基础数据：车源与估价、成品油价格、行政区划与地址。它们看似独立，实际经常要协同------比如一笔跨城物流报价，既要按线路各省市查当日油价，又要把订单里的野生地址对齐成标准行政区划。

这篇文章把车辆、能源、地理三大家族的数据接口梳理清楚，重点讲它们怎么配合，以及集成时计费与口径上的坑。

一、三大家族各自解决什么

家族	接口	核心能力
车辆	价格评估、车源拉取	算收车/挂牌参考区间、批量同步在售车源
能源	实时油价、全国批量、调价日历、调价预案、物流沿线油价	查当前价、建全国库、排程、提前拿新价
地理	地址清洗、行政区划代码	野生地址结构化、行政区划底库查询

二、车辆定价链路：先拉车源，再逐辆评估

车辆相关的两个接口天然是上下游关系。

车源拉取 ：返回一个在售车源列表，车型名称、图片、行驶里程、注册年份、首付、标签一次拿全，单位已经统一（里程统一万公里、首付统一万元），用 limit 控制条数。当前没有可查车源时不收费。

价格评估 ：传入最多 20 个车辆参数（品牌型号、上牌时间、里程、所在地、事故等级等），返回合理价格区间（万元）。影响权重最大的字段依次是：行驶里程 → 车龄 → 车辆所在地 → 事故历史。只给品牌型号也能出结果，但区间会明显变宽；补全上牌时间 + 里程后，区间通常收窄一半以上。评估不出价格时不收费。

python 复制代码

def price_one_car(api_call, base_params):
    """先拉车源，再对每辆做评估，得到可谈判的收车/挂牌价"""
    cars = api_call("car_list", limit=50)
    quotes = []
    for car in cars:
        params = {**base_params, "brand": car["brand"], "model": car["model"],
                  "mileage": car["mileage"], "registrationDate": car["regDate"]}
        data = api_call("car_price", **params)
        if data:
            # 收车取区间下限打折，挂牌取上限上浮，留谈判空间
            quotes.append((data["priceStart"] * 0.95, data["priceEnd"] * 1.05))
    return quotes

要点：评估类接口含模型推理，超时设 30 秒以上、并发要放低、结果缓存 7~30 天；同一辆车短时间重复评估没有意义。

三、油价四件套：免费排程、低价单查、高价建库、包年预查

油价接口有四个，分工非常明确，选错会直接浪费钱：

调价日历（免费）：返回某一年已登记的调价生效日期列表，十几毫秒返回。它不告诉你今天多少钱，但告诉你「哪天该干活」，用来给定时任务排程。
实时油价（低价）：按省/市/区县 + 油品名查询，返回当前生效的发改委价格。适合单点、按需查询。
全国批量（高价）：一个请求不带参数，返回当前生效批次下全部地区、六种油品（0#/-10#/-35# 柴油、92#/95#/98# 汽油）的价格。适合建本地库、做大屏、做批量测算。
调价预案（包年） ：查询时把基准时间推后 2 小时，只要平台已录入下一批次，就能在 0 点生效前 2 小时拿到新价，用 advance 字段判断是否新价。

物流沿线油价测算，本质是按线路的各省市逐个调实时油价，把沿线价格灌进成本模型。

要点：如果只关心 3 个省份，用实时油价查 3 次，比调一次全国批量便宜得多。

四、地理基础设施：地址清洗 + 行政区划代码

行政区划代码（免费）：支持按代码精确查、按名称模糊查、按省市下钻，还能直接拉省级或地市级清单，返回省市区三级名称、6 位 adcode、邮政编码、拼音，数据每周同步。它是地址清洗、区域报表、运费模板、配送范围校验的底座。

地址清洗：输入一段中文文本（用户从聊天窗口粘过来的一整段姓名电话地址），输出姓名、电话、省/市/区县三级规范名称与 adcode、详细地址、邮政编码。解析不出省级行政区时不收费，适合存量数据批量治理。

python 复制代码

def enrich_order(api_call, raw_address: str):
    """订单地址 -> 标准行政区划 -> 后续可匹配油价/配送范围"""
    parsed = api_call("address_parse", text=raw_address)
    if not parsed or not parsed.get("province"):
        return None   # 解析不出省级，不计费，转人工
    return {
        "province": parsed["province"],
        "city": parsed["city"],
        "district": parsed["district"],
        "adcode": parsed["cityCode"] or parsed["provinceCode"],
        "zip": parsed["zipCode"],
    }

五、一个协同示例：跨城物流报价

把三大家族串起来，就是一笔完整的跨城报价：

地址清洗：把起点/终点的野生地址解析成 adcode；
行政区划：用 adcode 校验、补全沿途省市清单；
实时油价：按沿途各省市查当日柴油/汽油指导价；
成本测算：里程 × 油耗 × 沿线油价，得出燃油成本；
叠加过路费、人工、损耗，输出分区报价模板。

这条链路里，地理是底座，能源是变量，车辆（如果涉及车源定价）是另一路独立分支。

六、集成时最容易踩的坑

计费时机三套口径。查不到不收费（车源、评估、地址清洗、行政区划、调价日历、实时油价的部分场景）、鉴权通过即扣费（全国批量、实时油价）、包年内不额外扣费（调价预案）。全国批量是重接口，参数错、查不到也都已计费，别和「查不到不收费」混用。
null 有两种含义 。价格字段 null 表示该油品该地区未维护（如南方多无 -35# 柴油），展示写「暂无」、计算时跳过，不能当 0；地区字段 null 表示统一定价（全省/全市统一价），落库时建议写成明确标记。
全国批量必须缓存、不能放用户链路。它是重接口，一次调价周期内拉一次即可，用生效日期做幂等。
包年接口 advance=false 是正常结果。只是平台还没录入下一批，代码里别当异常去重试或告警。
地区参数用 adcode 而非名称。名称必须完全匹配标准行政区划（传「重庆」会返回空列表），直接传 6 位 adcode 最稳。
评估接口超时 30 秒+、低并发。含模型推理，秒级并发容易把双方都拖慢。

七、小结

车辆、能源、地理三类数据接口，单独看是工具，串起来才是能力。车辆解决「这车值多少、有哪些在售」，能源解决「油多少钱、什么时候变」，地理解决「地址归哪里、adcode 是什么」。

落地的关键不在于调通某一个接口，而在于选对计费档位 （免费/低价/高价/包年各司其职）和对齐口径（null 的两种含义、地区用 adcode、批量必须缓存）。把这几条守住，整条数据链路就稳了。