指南

批量解析客户列表中的邮政编码

带有邮政编码列但没有坐标的客户导出数据,是处理配送区域、地区报表或门店分配等任务的常见起点。一次性解析整列数据比编写循环更快。

发送批量请求

向 /v1/postcode POST 一个由邮政编码和国家对象组成的数组。每一项都独立解析,并按相同顺序返回。

POST /v1/postcode
Content-Type: application/json

[{"code": "10115", "country": "DE"}, {"code": "75001", "country": "FR"}]
{
  "status": "ok",
  "results": [
    {"postcode": "10115", "country_code": "DE", "results": [{"lat": 52.5300, "lon": 13.3800, "components": {"city": "Berlin", "region": "Berlin"}}]},
    {"postcode": "75001", "country_code": "FR", "results": [{"lat": 48.8630, "lon": 2.3360, "components": {"city": "Paris", "region": "Ile-de-France"}}]}
  ]
}

将结果对应回客户记录

在发送请求之前,为每个邮政编码和国家组合保留原始行索引或客户 ID,并按相同位置将结果对应回客户记录,这与批量正向或逆地理编码的做法相同。

发送前先去重

任何具有一定规模的客户列表,其中不同的邮政编码往往远少于行数,因为在同一个城市或街区,许多客户共用同一个邮政编码。请先建立一份唯一的邮政编码和国家组合列表,用一次批量请求解析这份较小的列表,再把结果映射回共用每个邮政编码的所有客户行,而不是每个客户发送一个数组项、为同一个邮政编码和国家组合一次又一次地付费。

处理无法解析的邮政编码

某一项返回空的 results 数组,通常意味着该邮政编码和国家组合不存在,这在含有错别字或过时邮政编码的旧导出数据中很常见。请把这些行标记出来供人工审核,而不是悄悄地从报表中删掉。

一个边界情况:格式差异

不带空格存储的 “SW1A1AA” 和带空格存储的 “SW1A 1AA”,是否会以相同方式解析,取决于您自己的导出数据格式化邮政编码的一致程度。因此,在构建批量数组之前先规范导出数据中的空格和大小写,可以减少仅因格式问题(而不是邮政编码本身确实有误)而解析失败的行数。

成本是多少

批量请求按每项一次请求计费,因此一份 2,000 行的客户列表需要 2,000 次请求,无论是作为一次批量调用发送,还是作为 2,000 次单独调用发送。即便计入配额的请求数两种方式完全相同,作为一次调用发送仍然值得,因为开销更小,而且只需检查一组配额响应头。真正能减少请求数的是如上所述先去重,而不是在批量调用和单独调用之间做选择。

在批量处理过程中关注配额

如果列表大到会超出每天 2,500 次免费请求,请在决定一次性运行全部任务之前检查 X-Quota-Free-Remaining;如果您不打算为一次性任务改用预付额度,也可以把它分摊到两三天完成。

用一次调用解析整份客户列表的邮政编码,把过去缓慢的后台任务变成了一个简单直接的请求。邮政编码查询文档介绍了完整的字段列表。