Zip Code Lookup, Distance & Radius

Postal code lookup, distance between zips & radius search - 1.8M codes across 90+ countries, not just US.

原始信息汇总

数据总览

• 数据集名称：Zip Code Lookup, Distance & Radius
• 数据规模：覆盖全球 1.8M（180万）个邮政编码，横跨 90+ 个国家（包括美国 ZIP、英国 postcode、加拿大 FSA 等）。
• 数据来源：基于 GeoNames 邮政编码数据转储（CC-BY 许可），每月刷新一次，存储在磁盘上的 SQLite 索引中。
• 适用场景：构建店铺定位器、运费估算、服务区域检查、地址表单自动填写等。

核心功能（API 端点）

端点	方法	功能描述
/v1/zip/lookup	GET	解析邮政编码：返回对应的城市、州/地区、县、经纬度。支持智能匹配，无视空格、破折号和大小写。
/v1/zip/distance	GET	计算两个邮政编码之间的大圆距离（千米和英里）。
/v1/zip/radius	GET	查找指定邮政编码半径内的所有邮政编码，结果按距离升序排列，最多返回 200 条。
/v1/zip/lookup/bulk	POST	批量解析最多 100 个邮政编码，每个条目返回独立的查找结果，无法解析的条目返回 found: false 而不影响整批操作。

关键参数说明

参数	类型	说明
code	string	邮政编码（如 90210 或 SW1A 1AA）
country	string	ISO-3166 alpha-2 国家代码（如 US），用于过滤或限定范围
radius	number	半径搜索的距离，最大 500（默认 10）
unit	string	半径单位：km 或 mi（默认 km）
from / to	string	距离计算中的起点和终点邮政编码
codes	array	批量 lookup 中的邮政编码数组（最多 100 个）

响应字段

• country – ISO-3166 alpha-2 国家代码
• code – 邮政编码
• place – 地点/城市名称（可为 null）
• state – 州/省名称（可为 null）
• state_code – 州/省代码（可为 null）
• county – 县/二级行政区名称（可为 null）
• lat / lng – 纬度/经度（可为 null）
• distance_km / distance_miles – 距离结果（仅在 radius 端点返回）

错误码

HTTP 状态码	说明
422	无效的邮政编码格式、无效的国家代码、批量请求超过 100 个
404	未找到邮政编码，或已找到但缺少坐标（用于 distance/radius）
403	请求未通过 API 网关

付费方案

方案	月费	说明
BASIC	$0.00	免费使用
PRO	$7.99	进阶订阅
ULTRA	$19.99	高级订阅
MEGA	$49.99	最大订阅

其他特性

• 智能匹配：支持 ZIP+4（如 90210-1234）、加拿大完整邮编、大小写和空格无关。
• 数据刷新：每月更新一次数据源。
• 性能指标：服务等级 100%，平均延迟 75ms，测试通过率 100%，人气评分 8.5。