批量天气查询：返回的是对象，不是数组｜数据鱼API

一次查十个坐标的天气，听起来只是把十次单点请求合并。真正接入后，第一个绊脚石往往不是数量上限，而是返回结构：data.list 不是数组，而是以“纬度,经度”为键的对象，而且键只保留两位小数。

下面用数据鱼API提供的「全球天气查询」接口演示，调用的是「批量查询」分支（POST /v1/api/weather/batch）。批量查询最多 10 个坐标。

请求与返回

POST /v1/api/weather/batch，key 用于认证，locations 是坐标数组，最多 10 个。超过 10 个会被拒绝，请求参数说明写的是 400，返回字段说明里写的是 4002，两处不一致；接入时按 code 判断并给出明确提示，不要硬编码某一个错误码。

非法项（缺 lat 或 lng、非数字、超出范围）会被跳过并计入 data.invalid，data.invalid_count 是数量。全部非法返回 400；部分合法时返回 200，并附无效清单。

data.total、data.returned、data.max_limit 用于对账，data.truncated 是保留字段，当前恒为 false，data.elapsed_ms 是服务端耗时。

max_limit 是 10，可以写进前端提示，但不要把它当成服务端一定会接收的数量，提交前仍要自己校验。elapsed_ms 适合做性能日志，不适合直接作为超时阈值，网络耗时还要另算。

批量接口适合“多个城市天气看板”这类场景：一次拿十个点，减少往返次数。但它不适合替代全量同步，单次上限 10 个，城市多时仍然要分批。分批的边界按 10 切，不要凑整到 11 再期望服务端处理。

无效项怎么处理

invalid 清单里会带上被跳过的坐标，invalid_count 是数量。部分合法时接口返回 200，调用方不能因为顶层成功就忽略无效项。把无效坐标回显给用户或写入日志，下一轮修正后再提交，比整批重试更精准。

键为什么是字符串

data.list 的键形如 39.90,116.40，纬度和经度各保留两位小数。这意味着两个相差不到 0.01 度的坐标可能落到同一个键上，返回里只保留一份。批量前先按两位小数去重，能避免“少了一个点”的困惑。

响应体积

每个坐标点都包含 current、hourly 和 daily，十个点的响应体并不小。只要实况时，解析后立刻裁掉逐时和逐日，不要整段塞进缓存。缓存键用坐标字符串，值和单点查询的结构对齐，后续切换接口时不用改展示层。

接入清单

客户端先校验坐标范围和类型，按 10 个一组切分。用同一个舍入函数生成键，不要依赖返回顺序。校验 returned 与 invalid_count 之和是否和提交数量一致。每个点都含 current、hourly、daily，只要实况时在客户端裁掉后面两段。

def weather_batch(points):
    for i in range(0, len(points), 10):
        chunk = points[i:i + 10]
        resp = requests.post(
            f"{API_BASE}/v1/api/weather/batch",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"locations": chunk},
            timeout=15,
        ).json()
        data = resp["data"]
        for lat, lng in chunk:
            key = f"{lat:.2f},{lng:.2f}"
            yield key, data["list"].get(key), data

超时重试要按批进行，并且只重试失败的那一批。重试前先确认 locations 没有重复坐标，否则同一批里两个相同键会互相覆盖，返回条数对不上。

四个坑

第一，按数组下标取结果。data.list 是对象，键是坐标字符串，顺序不可依赖。

第二，坐标四舍五入后同键。两个点只差 0.001 度时，批量前先去重，不要等返回后才发现少了一个。

第三，把 11 个坐标的错误码写死成 400 或 4002。文档两处写法不同，按 code 做分支更稳。

第四，全部非法返回 400，被当成服务故障。先看 invalid_count 和 invalid 清单，再决定是否告警。

批量接口的价值是把多次往返压成一次，但返回结构需要重新映射。把键的生成规则和单点查询对齐，结果才不会错位。返回的键只是坐标索引，用户看到的仍然是城市或地点名称，需要额外映射。

示例接口由数据鱼API提供；不同版本的字段可能微调，正式接入前建议再核对一次文档。