开源整理了一份最新的行政区划代码（Adcode）对应邮政编码（Zipcode）数据，轻松根据地址获取邮编建立行政区划代码

前言

在开发一个表单需求时需要根据地址来填写邮编，高德、百度等主流地图 API 往往在地址解析（Geocoding）结果中并没有邮编。为了解决这个“最后一公里”的地址对应邮编问题，我整理并开源了这个项目：china-zipcode-data。开发时非常方便的实现地址匹配邮编

Demo预览：tombcato.github.io/china-zipco…

一、为什么要做这个项目？

1. 开发时邮编获取的困局

调研了下市面上的邮编数据API, 通过地址信息获取邮编需要付费限免次数有限
通过AI获取的邮编数据幻觉严重，实测多个模型都无法返回准确邮编
有很多网页提供三级联动查询区域邮编，但无法通过api接入项目
有一些开源数据但内行政区划老旧不准确，获取邮编还需要手动拆分输入地址的省市区来进行匹配，不准还麻烦

2. 地图 API 的“断层”

在使用地图 SDK 时，最常用的流程是： 输入地址 -> 地图地理编码 -> 行政代码(Adcode) / 经纬度 / 格式化后的地址等。然而，邮编作为一个相对传统的字段，在现代地图服务中的权重在降低。即使拿到了详细地址以及行政区域编码(Adcode)，也无法获取到对应的邮编。

3. 数据的时效性问题

邮编数据，要么是 2018 年之前的陈旧版本，不少是付费下载的。
行政区划数据，随着近年来国内行政区划的频繁调整（撤县设区、新区合并），最新对应数据变得非常稀缺。

注意：自2024年10月起，国家统计局继续公开《关于统计上划分城乡的规定》《统计用区划代码和城乡划分代码编制规则》等统计标准方法，不再公开具体相关代码

二、解决方案

通过建立行政区划代码（Adcode）对应邮政编码（Zipcode）的关联数据来方便实现查询，将数据导出为JSON，各种语言都可以基于此数据方便开发

最新数据：参考了《2023年中华人民共和国县以上行政区划代码》与高德API返回区域代码手动校对邮编。高德全国邮政编码查询
Adcode 关联：不仅是名字匹配，且是基于标准的行政区划代码 Adcode 匹配，极速方便。
极小体积：经过数据去重与结构优化，JSON 压缩后极小，加载无压力。
全环境支持：支持纯 JSON 导入、ESM 模块加载、甚至浏览器 CDN 零配置调用。

三、项目实现与技术细节

该项目不仅是一份数据，还配套了一套轻量级的 JavaScript SDK。

1. 数据结构设计

为了兼顾搜索效率和体积，我们采用了扁平化的 JSON 结构，涵盖了全国 3000+ 区县：

{
    "code": "110105",
    "name": "朝阳区",
    "cityCode": "1101",
    "provinceCode": "11",
    "province": "北京市",
    "city": "北京市",
    "zipCode": "100020",
    "pinyin": "chao yang"
}

2. SDK 核心逻辑

SDK 提供了两个核心方法：

get(adcode)：O(1) 级别的精确查找，秒回结果。
search(query, city, province)：支持关键词、拼音、Adcode 的组合模糊搜索。

npm install @tombcato/china-zipcode-data

import { get, search } from '@tombcato/china-zipcode-data';

// 1. 通过 Adcode 拿邮编（最推荐、最准）
const res = await get('110105'); 

// 2. 模糊搜索
const list = await search('朝阳', '北京');

3. 极简的 CDN 集成

如果你只是写个轻量级的 Demo 或静态页，甚至不需要 npm install：

<script type="module">
  import { get } from 'https://cdn.jsdelivr.net/npm/@tombcato/china-zipcode-data@latest/+esm';
  // ... 直接使用
</script>

4. Demo 体验

为了让大家直观感受这套数据，项目还附带了一个使用 Alpine.js + Tailwind CSS 开发的演示页面。支持：

地址一键解析：调取高德接口拿到 Adcode再匹配邮编。
省市区联动：经典的三级下拉选择获取邮编。
Adcode搜索：手动输入行政编码返回邮编。
模糊搜索：通过名称可选限定城市或省份搜索邮编。
点击复制：点击邮编即可复制到剪贴板。

结语

开源这个项目的初衷是希望能帮到同样在处理地址、邮编、行政区划逻辑转换中受苦的dev。

如果你由于业务需要发现其中的数据有误，或者有更好的优化建议，欢迎来提 Issue 或 PR！

项目地址：github.com/tombcato/ch…
在线体验：tombcato.github.io/china-zipco…

如果觉得有用，点个 Star 就是对我最大的鼓励！

开源整理了一份最新的行政区划代码（Adcode）对应邮政编码（Zipcode）数据，轻松根据地址获取邮编

前言

一、 为什么要做这个项目？