简介面向物流配送、地图服务与区域统计分析等场景整理的中国行政区划邮编与经纬度数据集合覆盖省、市、区、县、乡、镇、街道层级共约46090条记录以结构化SQL表形式存放便于直接导入关系型数据库做查询、关联与二次开发。压缩包内共1个文件为SQL脚本整体约942KB字段可支撑按行政层级检索、坐标定位及区域划分等基础工作适合GIS入门者、后端开发与数据分析人员快速验证地址匹配、配送范围测算等需求。已有796人学习下载。数据以表格组织每行对应一个行政区域包含行政区名称、邮政编码及经纬度等字段可直接用于地图标注、物流路径优化、市场区域细分、政府规划参考和灾害响应定位配合SQL查询还能与人口、经济等指标关联形成更完整的区域分析底表减少从多源渠道拼装清洗坐标与邮编的成本。1. 五级行政区划带邮编和坐标难点从来不在“抓”而在“对”做门店选址、快递分单、区域报表的人迟早会撞上同一件事手里只有一串“省市区县乡镇街道”的文本系统要的却是能下钻、能定位、能算距离的结构化数据。于是就有了「全国省、市、区、县、乡、镇、街道邮编及经纬度坐标」这类需求——它本质是一张覆盖五级行政单元、每行带邮政编码和经纬度坐标的底表。听着像纯抓取的活真做下去会发现抓数据只占三成剩下七成是编码对齐、坐标系统一和边界核对。这篇把我自己做这套表的完整路径拆开数据源怎么挑、表怎么设计、地理编码怎么批量跑、坐标怎么验、哪几个地方必翻车。适合要自己维护一份地址底表的后端和数据同学也适合被“地址对不上”折磨过的业务开发。2. 数据源不能只挑一个行政区划代码、邮编、坐标该分别信谁先把一个错觉捅破不存在一个“全都对”的源。行政区划代码、邮政编码、经纬度坐标这三块数据的产生机制完全不同——代码是行政编制部门按区划调整发布的跟着撤县设区、撤乡并镇天天变邮编是邮政投递网络划定的范围跟行政边界根本不是一回事坐标是地图服务商按自己的采集和加密规则给出的点同一栋楼在不同平台能差出几百米。指望一个接口把三者一起吐出来最后一定是某个维度悄悄错了而你没发现。我一般的做法是三源并行、职责分离行政区划代码做骨架和主键邮编做附加属性且允许一对多坐标单独一张点位表按坐标系标注来源。三张表之间用行政区划代码串起来出了问题能定位到是哪一环错的而不是对着一张大宽表猜。这套思路在第一次做的时候会觉得麻烦等你遇到第二次区划调整就知道省了多少返工。2.1 五级代码的位数规则6 位、9 位、12 位分别锁住哪一级行政区划代码不是一串随便的数字它是有严格分段含义的。最常见的是 6 位码前 2 位是省级、中间 2 位是地级、后 2 位是县级省级码的后四位补零地级码的后两位补零。这套 6 位规则是绝大多数业务系统里“地区表”的基础。但 6 位码到县级就断了街道乡镇这一层要往上加 3 位变成 9 位村和社区再加 3 位变成 12 位。所以如果你要做“省市区县乡镇街道”五级实际用到的是 6 位和 9 位两套如果还想下钻到村居就得用 12 位。这三套码之间是前缀包含关系12 位码的前 9 位一定是它所属的乡镇码前 6 位一定是它所属的区县码——这个性质是做层级还原的全部依据。层级代码位数分段含义补零规则典型用途省级2 位有效 / 6 位前 2 位后 4 位为 0大区统计、报表分组地级4 位有效 / 6 位前 2 中 2后 2 位为 0城市维度聚合县级6 位前 2 中 2 后 2无地址主键、区县下钻乡级9 位6 位 3 位无街道乡镇派单、网格村级12 位9 位 3 位无末端配送、社区治理注意最后一行村级码虽然存在但它的更新频率和可获得性远不如前四级很多公开数据只到乡级。如果你的业务不需要村居粒度就别贪多把 9 位作为最小粒度维护成本会低一个量级。还有一个容易被忽略的点省级码里有一批“特殊段”比如直辖市、自治区、以及省直辖的县级行政单元。省直辖县级市在 6 位码里的位置是“省级码 90 左右的段 县级码”它没有地级父节点。如果你按“前 4 位当地级”去硬拆这类单元会被解析成一个不存在的市后面所有层级都错位。处理方式是在层级字段里显式标记一个“省直辖”类型还原父子关系时走特判分支而不是靠位数硬切。2.2 邮政编码是投递范围不是行政范围别拿它当外键邮编是 6 位数字结构上大致是“前 2 位大区、第 3 位省、第 4 位邮区、后 2 位投递局”。看起来像层级实际上它描述的是一套投递网络跟行政区划是两套并行的划分体系两者只在大部分时候重合在边界地带经常打架。最典型的三种不一致一个区县横跨多个邮编比如城区和下面的乡镇邮编不同一个邮编覆盖多个区县尤其是城区密集地带几个区的部分街道共用一个投递局街道乡镇这一级邮编基本不可靠很多街道根本没有独立邮编只能沿用上级区县的码。所以如果你把邮编当主键、或者做“邮编 → 区县”的反查表一定会在边界数据上翻车。我的处理是把邮编放在一个独立的关联表里一对多主表只保留一个“代表邮编”用于展示实际分单、路由一律以行政区划代码为准。代表邮编的选取规则也很简单优先取区县主城区对应的那个码取不到就取该区县下出现频次最高的码并在字段里标注是“精确”还是“继承”。这个标注看着多余等到业务方拿着邮编投诉“为什么我这条地址邮编不对”时你就知道它有用了。需要提醒的是邮编本身在逐年弱化快递分单早就以“省市区 详细地址 末端网点”为主邮编更多是报关、传统信函和部分政务表单的要求。所以这块的数据精度做到区县级就够用不必死磕街道级邮编——那是个投入产出比极低的坑。2.3 建表一张能同时扛住五级下钻和点位查询的表表设计的核心决策是“宽表还是分层表”。宽表查询快、导出方便但坐标一改就得整行更新而且一个行政单元可能有多个点位政府驻地、辖区中心、几何质心宽表塞不下。分层表灵活但每次下钻都要递归。我最终的方案是折中一张行政区划主表存层级和名称一张点位附表存坐标邮编走单独的关联表。CREATE TABLE admin_division ( adcode VARCHAR(12) NOT NULL COMMENT 行政区划代码9位或12位, parent_code VARCHAR(12) NOT NULL DEFAULT COMMENT 父级代码省级为空串, level TINYINT NOT NULL COMMENT 1省 2地级 3县级 4乡级 5村级, div_type TINYINT NOT NULL DEFAULT 0 COMMENT 0普通 1直辖市 2省直辖县级 3开发区/新区, name VARCHAR(64) NOT NULL COMMENT 标准全称, short_name VARCHAR(32) NOT NULL DEFAULT COMMENT 简称用于地址拼接, full_path VARCHAR(255) NOT NULL DEFAULT COMMENT 省/市/区/乡 拼接路径, is_active TINYINT NOT NULL DEFAULT 1 COMMENT 1有效 0已撤销, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (adcode), KEY idx_parent (parent_code), KEY idx_level_name (level, name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT行政区划主表; CREATE TABLE admin_point ( id BIGINT NOT NULL AUTO_INCREMENT, adcode VARCHAR(12) NOT NULL, point_type TINYINT NOT NULL COMMENT 1政府驻地 2几何质心 3地图POI命中点, lng DECIMAL(10,6) NOT NULL COMMENT 经度, lat DECIMAL(10,6) NOT NULL COMMENT 纬度, coord_sys VARCHAR(16) NOT NULL COMMENT WGS84 / GCJ02 / BD09, source VARCHAR(32) NOT NULL COMMENT 数据来源标识, confidence TINYINT NOT NULL DEFAULT 3 COMMENT 1高 2中 3低, PRIMARY KEY (id), KEY idx_adcode_type (adcode, point_type) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT行政单元点位附表; CREATE TABLE admin_postcode ( adcode VARCHAR(12) NOT NULL, postcode CHAR(6) NOT NULL, match_level TINYINT NOT NULL COMMENT 1精确到该单元 2继承自上级, PRIMARY KEY (adcode, postcode) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT邮编关联表;这三张表的取舍逻辑值得说清楚。adcode用 VARCHAR 而不是 INT因为代码里有前导零省码“11”存成 INT 会变成 11拼前缀时补零补错一位就全错level和div_type分开而不是合并是因为“省直辖县级”这种单元既要标层级又要标特殊类型合在一个字段里查询会很难写admin_point里coord_sys这个字段是必须的没有它你就分不清这条坐标能不能直接和业务里的 GPS 坐标算距离。full_path是个冗余字段用空间换时间。地址拼接、模糊搜索、导出报表都靠它否则每次都要递归五层。代价是任何一级改名都要级联更新所以我在数据同步流程里加了一步“改名检测”对比新旧快照只要有 name 变化就批量刷新该节点及其所有子孙的full_path。这一步不做线上就会出现“父级叫新名、子级路径里还是旧名”的诡异数据。confidence这个字段在后期排错时价值极高。同样一个街道来自官方代码库的坐标和来自地图 POI 搜索的坐标可信度差得很远。把置信度写进表里做距离校验时就能只对低置信度的记录做人工复核而不是全量重跑。3. 把五级拉平成一张宽表代码解析、层级重建与边界校验拿到原始代码列表之后第一件事不是入库是还原层级。很多公开数据下发的是扁平列表一条条记录带着自己的代码和名称但父子关系要么没给要么给的是“父级名称”这种不可靠字段——因为名称会重名。第一章说过 12 位码有前缀包含性质这就是免费的父子关系比自己猜要稳得多。3.1 用前缀法还原父子关系顺手把省直辖单元挑出来前缀法的实现很直接对每个 9 位或 12 位码按位数规则截取上级码再去全量集合里查是否存在。存在就挂上不存在就说明上级缺失或者这个节点属于特殊类型。这段逻辑我写成了一个可反复跑的函数每次数据更新都全量重建一遍父子关系不做增量因为增量维护父子指针在区划调整时几乎必错。from collections import defaultdict # 各级别对应的代码长度键是子级值是父级 PARENT_LEN {12: 9, 9: 6, 6: 4, 4: 2} def resolve_parent(adcode: str, all_codes: set) - str: 按位数规则向上找父级找不到返回空串 code adcode.rstrip() for cur_len, parent_len in PARENT_LEN.items(): if len(code) cur_len: # 6位码里省级是后4位为0地级是后2位为0要区分 if cur_len 6: if code.endswith(0000): return if code.endswith(00): return code[:2] 0000 return code[:4] 00 parent code[:parent_len].ljust(len(code), 0) return parent if parent in all_codes else return def build_tree(rows: list) - list: rows: [{adcode: 110101001001, name: 某居委会}, ...] 返回补全 parent_code / level / div_type 的记录 all_codes {r[adcode] for r in rows} out [] for r in rows: code r[adcode] parent resolve_parent(code, all_codes) level {2: 1, 4: 1, 6: 3, 9: 4, 12: 5}.get(len(code), 5) # 6位码单独判层级 if len(code) 6: if code.endswith(0000): level 1 elif code.endswith(00): level 2 else: level 3 div_type 0 if level 2 and code[:2] in (11, 12, 31, 50): div_type 1 # 直辖市 if level 3 and not parent: div_type 2 # 省直辖县级无地级父节点 out.append({**r, parent_code: parent, level: level, div_type: div_type}) return out这里的逻辑说明几点。ljust是用来给父级码补零的因为截断之后的父级码长度不够必须补到和原码一样的位数才能在集合里匹配上——比如 12 位码截前 9 位得到 9 位父码本身长度就对了但如果从 9 位往 6 位找截前 6 位得到的就是 6 位不需要补真正需要补的是省级这种“2 位有效 4 位零”的情况所以我在 6 位分支里单独写了判断而不是靠ljust硬补。div_type的判断是这套代码里最容易被砍掉、又最不能砍的部分。直辖市在 6 位码里是“省级码 0000”它下面直接挂区没有地级这一层如果按常规四级结构去还原会得到一条“直辖市 → 某区”的父子对但level会算成 1 和 3中间缺了一层前端做三级联动时就会断。省直辖县级市同理它挂不到任何地级父节点上parent返回空串如果不打标入库时会被当成数据缺失给过滤掉。跑完这一步level分布应该是一个稳定的金字塔省级三十多个地级三百多个县级两千八百多个乡级四万多个。如果某一级的数量明显偏离这个量级不用怀疑一定是父级还原出问题了回头查代码格式——最常见的是原始数据里混进了 6 位码和 9 位码两种粒度被当成同一批处理。3.2 街道级数据补齐的两条路官方代码库与地图 POI 的偏差县级以上的数据相对好拿街道乡镇这一层才是分水岭。我的经验是走两条路互相兜底官方发布的统计用区划代码作为权威骨架保证“有哪些街道、代码是什么”不出错地图服务商的 POI 搜索结果用来补坐标和纠正常见别名保证“这个街道在哪”有落点。权威骨架的价值在于完整性。它给出的街道列表是穷举的不会漏缺点是更新有滞后——某地新设了一个街道代码库里可能半年后才出现。地图 POI 的价值在于时效性和坐标缺点是召回不稳定搜“某某街道”可能返回街道办事处、可能返回同名社区、也可能返回一个商圈名甚至返回隔壁县的同名街道。所以补齐流程我是这么设计的先以权威骨架为准建全量节点然后用“省 市 区 街道名”拼成查询串去地图侧取点位取回来的结果必须过两道过滤——一是行政区划包含校验点位必须落在上级区县的边界内二是名称相似度校验返回名称要包含街道名的主体部分。两道都过才写入point_type3、confidence2只过一道的进待复核队列一道都不过的直接丢弃宁缺毋滥。这里有个反直觉的结论街道级坐标的准确率瓶颈不在接口质量在名称规范度。同一个街道官方叫“某某街道办事处”地图上叫“某某街道”民间叫“某某”三种写法搜出来的结果差别很大。我在清洗阶段会把“街道办事处”“办事处”“街道”这几个后缀统一剥离只留主体名再拼上级行政区去搜命中率和准确率都能明显提升。这个细节后面第 4 章还会展开。3.3 自动挑脏数据三类校验规则和对应处置数据入库不等于可用还得有一层校验把脏数据挑出来。我固定跑三类规则跑完输出一份异常清单人工只看清单不看全量。第一类是层级完整性校验每个非省级节点必须有父节点每个节点的level必须等于父节点level 1唯一例外是div_type1的直辖市和div_type2的省直辖县级。这条规则能抓出 90% 的解析错误。第二类是名称重复校验同一父节点下不允许同名子节点跨父节点同名是正常的全国重名的镇非常多但要在表里留一个“同名组”标记供后续地理编码时做区分。这条规则抓的是数据源混入了重复行。第三类是坐标越界校验每个点位的坐标必须落在其上级区县的几何边界内或者至少落在上级地级市的边界内。没有边界数据的话退化成一个粗略的矩形框校验也行——用上级节点的中心点和半径做一个缓冲区超出缓冲区的标记为可疑。这条能抓出地理编码串到外省的情况实测抓得挺准。def check_coord_in_bbox(lng, lat, center_lng, center_lat, radius_km80): 粗略的矩形框校验radius_km 按地级市尺度取 60~100 # 纬度 1 度约 111km经度按当前纬度收缩 import math dlat radius_km / 111.0 dlng radius_km / (111.0 * math.cos(math.radians(center_lat)) 1e-9) return (abs(lng - center_lng) dlng) and (abs(lat - center_lat) dlat)radius_km这个参数要按层级调县级用 30 到 50地级用 80 到 120。设太小会把辖区边缘的正常点位误判成异常设太大又抓不住串区。我的做法是先按 80 跑一遍看异常率如果超过 5% 就把半径放宽一档再跑反复两次基本能定到一个合适的值。这套阈值没有普适解得按你数据的实际分布调别人的参数抄过来大概率不合用。4. 批量取经纬度输入清洗、限流重试和坐标系统一到这一步骨架有了、点位缺了剩下的活是把几万个街道名批量换成坐标。听起来是调接口的体力活实际上三个地方决定成败查询串怎么拼、失败怎么分类重试、坐标回来之后怎么统一。4.1 输入侧清洗把“某某街道”拼成能被地理编码命中的地址串地理编码接口对输入格式非常敏感。直接拿“某某街道”去搜返回的可能是同名的省外节点拼成“省 市 区 某某街道”命中率立刻上一个台阶。但拼接本身也有讲究拼错了反而降低命中率。第一个讲究是行政区名称要用“标准简称”而不是“全称”。全称里带“省”“市”“区”“自治县”这些后缀接口做分词时会切得很碎用简称则更接近人们日常表达的地址。所以我建表时留了short_name字段专门用于地址拼接比如全称去掉末尾的行政后缀。少数民族自治地方的名称有特殊性不能简单截断得单独维护一个小映射表。第二个讲究是街道名的后缀处理。前面提过“某某街道办事处”要剥成“某某”但剥离之后要去重——有些地方存在“某某街道”和“某某镇”同名的情况剥完就撞了。撞名的情况下保留原始后缀让接口自己判断。第三个讲究是拼接顺序和分隔符。我统一用“省简称 市简称 区县简称 街道名”中间不加空格不加逗号因为大多数接口对连续中文字符串的处理最稳。加了逗号反而可能被当成多段地址分别解析。SUFFIX_MAP {省: , 市: , 区: , 县: , 自治县: , 旗: } def clean_name(full_name: str, keep_suffix: bool False) - str: 剥离行政后缀keep_suffix 用于重名场景 if keep_suffix: return full_name for suf in (街道办事处, 办事处, 街道, 镇, 乡): if full_name.endswith(suf) and len(full_name) len(suf): return full_name[:-len(suf)] return full_name def build_query(row: dict, parent_map: dict) - str: row 需要含 adcode/nameparent_map 是 adcode - 记录 的字典 parts [] cur row while cur: parts.append(clean_name(cur.get(short_name) or cur[name])) cur parent_map.get(cur.get(parent_code)) parts.reverse() parts.append(clean_name(row[name], keep_suffixTrue)) return .join(parts)build_query是从当前节点一路往上走到省级把各级简称收集起来再反转最后把本节点的名字带后缀方便接口区分街道和镇追加到末尾。这样拼出来的串形如“某省某市某区某某街道”没有多余字符。keep_suffix这个开关就是为重名场景准备的先跑一遍全量把所有拼出来的串做一次去重统计撞名的那些记录标记出来第二次跑时把这批改成keep_suffixTrue重试。实测撞名比例大概在 1% 到 3% 之间主要是“某某镇”和“某某街道”并存的地方以及部分历史沿革导致的同音不同字。4.2 并发、限流和失败分类重试不能一把梭批量跑接口必须有并发控制但并发数不是越高越好。多数公开地理编码服务的配额是按 QPS 计的超了直接返回限流错误而你如果把这当成普通失败去重试只会把配额烧得更快。我的做法是三层控制并发数固定在一个保守值请求之间加固定间隔失败按错误码分类处理。分类是关键。网络超时和 5xx 归为“可重试”退避时间按指数增长4xx 里的参数错误归为“不可重试”直接记失败原因限流错误单独一类遇到就整体降速并把当前批次打回去重跑。如果不做这个分类一律重试三次最后的失败率会虚高而且日志里全是同一种错误根本看不出真实原因。import time, random from collections import Counter RETRY_BACKOFF [1, 3, 9] # 三次重试的等待秒数 QPS_INTERVAL 0.12 # 单请求最小间隔约 8 QPS def fetch_with_retry(session, url, params, stats: Counter): for attempt in range(len(RETRY_BACKOFF) 1): time.sleep(QPS_INTERVAL random.uniform(0, 0.03)) try: resp session.get(url, paramsparams, timeout5) except Exception as e: stats[timeout] 1 if attempt len(RETRY_BACKOFF): time.sleep(RETRY_BACKOFF[attempt]) continue return None, timeout if resp.status_code 200: body resp.json() if body.get(status) ok and body.get(result): stats[ok] 1 return body[result], None stats[empty] 1 return None, empty if resp.status_code 429: stats[rate_limited] 1 time.sleep(RETRY_BACKOFF[min(attempt, 2)] * 2) continue if 500 resp.status_code 600: stats[server_err] 1 time.sleep(RETRY_BACKOFF[attempt]) continue stats[client_err] 1 return None, fhttp_{resp.status_code} return None, retry_exhaustedQPS_INTERVAL这个值要按你拿到的配额倒推配额是 10 QPS就把间隔设在 0.12 秒左右留一点余量。RETRY_BACKOFF用 1、3、9 三档是因为大多数限流窗口是按秒或分钟计的等 9 秒基本能跨过窗口。status empty单独统计很重要——它代表接口通了但没搜到结果属于数据问题不是网络问题这部分记录要回流到清洗环节重新拼查询串而不是继续重试。跑完之后看stats的分项ok占比低于 85% 就说明输入清洗有问题empty占比高通常是后缀处理或简称映射错了rate_limited占比高就把间隔调大。这套指标比“总成功率”有用得多。4.3 坐标系统一GCJ-02、WGS84、BD-09 混用是最隐蔽的错坐标回来之后最容易埋雷的地方来了。国内主流的互联网地图服务给出的坐标大多是在 WGS84 基础上做过非线性偏移的 GCJ-02还有一类厂商用自己的二次偏移坐标系业内常称 BD-09。而 GPS 设备、北斗模块、大部分开源地理数据给的是标准 WGS84。这三套坐标如果不加区分地混在一张表里算出来的距离能差几百米而且偏差不是固定值随经纬度变化——这就是它最坑的地方你没法用一个固定偏移量修正。我的铁律是入库必标coord_sys跨系计算前必转。转换只做两件事——GCJ-02 与 WGS84 互转以及 GCJ-02 与厂商私有坐标系互转。前者的算法是公开的后者通常就是在 GCJ-02 上再做一次固定公式变换。import math A 6378245.0 EE 0.00669342162296594323 def _out_of_china(lng, lat): return not (73.66 lng 135.05 and 3.86 lat 53.55) def _transform_lat(x, y): ret -100.0 2.0*x 3.0*y 0.2*y*y 0.1*x*y 0.2*math.sqrt(abs(x)) ret (20.0*math.sin(6.0*x*math.pi) 20.0*math.sin(2.0*x*math.pi)) * 2.0/3.0 ret (20.0*math.sin(y*math.pi) 40.0*math.sin(y/3.0*math.pi)) * 2.0/3.0 ret (160.0*math.sin(y/12.0*math.pi) 320*math.sin(y*math.pi/30.0)) * 2.0/3.0 return ret def _transform_lng(x, y): ret 300.0 x 2.0*y 0.1*x*x 0.1*x*y 0.1*math.sqrt(abs(x)) ret (20.0*math.sin(6.0*x*math.pi) 20.0*math.sin(2.0*x*math.pi)) * 2.0/3.0 ret (20.0*math.sin(x*math.pi) 40.0*math.sin(x/3.0*math.pi)) * 2.0/3.0 ret (150.0*math.sin(x/12.0*math.pi) 300.0*math.sin(x/30.0*math.pi)) * 2.0/3.0 return ret def wgs84_to_gcj02(lng, lat): if _out_of_china(lng, lat): return lng, lat dlat _transform_lat(lng - 105.0, lat - 35.0) dlng _transform_lng(lng - 105.0, lat - 35.0) radlat lat / 180.0 * math.pi magic math.sin(radlat) magic 1 - EE * magic * magic sqrtmagic math.sqrt(magic) dlat (dlat * 180.0) / ((A * (1 - EE)) / (magic * sqrtmagic) * math.pi) dlng (dlng * 180.0) / (A / sqrtmagic * math.cos(radlat) * math.pi) return lng dlng, lat dlat def gcj02_to_wgs84(lng, lat): 一次迭代反解精度足够业务使用 glng, glat wgs84_to_gcj02(lng, lat) return lng * 2 - glng, lat * 2 - glat这几个函数里_out_of_china的边界判断不能省境外坐标不应该做偏移否则会把正常数据改坏。gcj02_to_wgs84用的是“正算两次取差”的近似反解误差在米级做区域统计、距离排序完全够用如果要做高精度测绘得换成迭代反解但那已经超出这类业务表的范围了。实际使用时还有一条经验转换之后的坐标要写回表并更新coord_sys不要每次查询时实时算。实时算的问题是同一个点在不同代码路径里可能被转两次转两次的偏差会累积而且是那种查不出来的玄学偏差——数据看着都对就是算出来的距离不对。这个坑我踩过一次排查了整整两天最后发现是某个导出任务多转了一道。5. 避坑与排查五级地址表上线前最容易翻车的五个地方下面这几条都是从翻车现场攒下来的每条按“现象、原因、解决”写遇到的时候直接对号入座就行。第一条某批区县的街道数据整批为空日志里没有任何报错。现象是跑完之后发现某些区县下面一个乡级节点都没有但接口调用记录显示成功。原因通常有两个一是这些区县在原始数据里用 6 位码给了没有下钻到 9 位脚本按 9 位找自然找不到二是这些区县是近年新设的坐标系和代码库版本对不上。解决方式是加一步“覆盖率检查”——按level3遍历所有区县统计其下level4的节点数为 0 的直接进异常清单。这个检查一定要放在流程里不能靠人眼扫。第二条地理编码返回的坐标落在隔壁省距离差几百公里。现象是抽样看坐标明显不在本省范围内。原因是查询串拼得太短比如只用了“某某镇”而全国重名的镇有几十个接口按热门度返回了另一个。解决办法前面说过拼接必须带完整上级路径另外加一道边界校验作为最后防线超出上级地级市缓冲区的一律打回重查。血泪经验是边界校验的阈值宁紧勿松误判成异常的记录看一眼就能确认漏判成正常的记录可能几个月都没人发现。第三条同一个街道附表和主表里的坐标差了十几公里。原因是点位类型混用——街道办事处驻地和辖区几何质心是两个完全不同的点前者往往偏在辖区一角后者在中心。如果业务算服务半径用驻地会严重低估覆盖范围。解决方式是在附表里用point_type严格区分业务查询时显式指定要哪一种不要写“取任意一条”。默认规则我定的是算距离用几何质心做行政中心展示用政府驻地两个都缺才退回 POI 命中点。第四条直辖市和省直辖县级市在三级联动里断档。现象是前端选完省之后市这一级是空的或者跳过了。原因就是第 3 章说的这类单元的层级结构和常规不一样如果前端按“省 → 市 → 区”硬套三级中间那级取不到值。解决方式是在接口层做一次扁平化对于div_type1或2的节点直接返回“省级 区县”两级前端的联动组件要支持“动态层级”——即某一级可以跳过。这个改动不大但必须在设计阶段就定下来等前端写完再改成本很高。第五条邮编和行政区划对不上业务方反复来问。现象是某条地址的邮编和区县不匹配但查下来两边数据都没错。原因是邮编更新滞后于区划调整或者该地本来就一个邮编覆盖多个区。解决方式不是修数据是修预期在接口返回里把match_level带出去明确告诉调用方这个邮编是精确到该单元的还是从上级继承来的。承接方看到“继承”就知道不该拿它做主键。这条说起来是产品沟通问题实际是数据表设计问题——当初没留这个字段后面就只能一遍遍解释。这五条之外还有一类不算坑但要提前想清楚的事数据更新频率。区划调整每年都有频率不高但影响面大。我的做法是每季度全量同步一次同步时保留历史快照用is_active标记撤销节点而不是物理删除。物理删除的后果是历史订单里的老地址关联不到节点报表直接出现空洞那时候想补都补不回来。6. 坐标精度怎么验距离抽检、边界包含和一份可复用的验收脚本数据跑完不等于能交付还得有一套能量化的验收。我常用的三个手段从粗到细依次是距离抽检、边界包含校验、以及与已知参照点比对。距离抽检最省事随机抽一批乡级节点算它的点位到其上级区县几何质心的距离按地级市尺度设一个上限比如 80 公里超出的挑出来人工看。这个方法能抓住明显的串区错误。参数上不要把上限设得太死山区和面积大的县很容易正常超限我一般先按 100 公里跑看异常率再逐步收紧。边界包含校验更严格需要区县级的边界数据。做法是用射线法判断点位是否落在多边形内落在外面的标记可疑。边界数据可以从公开的地理信息数据集拿精度做到县级就够。这个方法的误报主要来自边界简化——简化后的多边形和真实边界有几十米差异边缘点位会被误判所以判定为“外”的点位要再用距离阈值兜一层距边界 1 公里以内的不报。def ray_casting(lng, lat, polygon): polygon: [(lng, lat), ...] 闭合或非闭合均可 inside False n len(polygon) j n - 1 for i in range(n): xi, yi polygon[i] xj, yj polygon[j] if ((yi lat) ! (yj lat)) and \ (lng (xj - xi) * (lat - yi) / (yj - yi 1e-12) xi): inside not inside j i return inside def point_to_segment_km(p, a, b): 点到线段的最短距离单位公里用于边界容差判断 import math lng, lat p ax, ay a; bx, by b dx, dy bx - ax, by - ay if dx 0 and dy 0: return math.hypot(lng - ax, lat - ay) * 111.0 t ((lng - ax) * dx (lat - ay) * dy) / (dx*dx dy*dy) t max(0.0, min(1.0, t)) cx, cy ax t*dx, ay t*dy return math.hypot(lng - cx, lat - cy) * 111.0ray_casting是标准射线法注意分母加了1e-12防止水平边除零。point_to_segment_km用来算点到边界的最短距离判定在边界外但距离小于 1 公里的不报异常。这个容差参数按你边界数据的简化精度调简化得越狠容差要越大。第三个手段是与参照点比对。找一批确定无疑的点位——比如各省级行政中心、几个大城市的标志性地点——把你的表里对应的坐标和参照坐标算距离超过阈值的说明坐标系转错了。这个方法主要用来验证第 4 章那套转换函数有没有用对上下误差应该在 50 米以内超过就是转错方向或者多转了一次。验收的产出不是一篇文章是一份异常清单加三个比例覆盖率、越界率、抽检偏差中位数。覆盖率低于 95% 说明缺数据越界率高于 2% 说明地理编码有问题偏差中位数超过 200 米说明坐标系或者点位类型选错了。这三个数字卡住数据基本就能交付。我自己最常犯的错是把“跑通了”当成“跑对了”。第一次做这套表的时候脚本一把过、几万条记录全绿我直接发了结果业务方拿去算门店覆盖发现郊区的乡镇全被算到市区去了。后来才知道那批乡镇的坐标是地理编码按“某某镇”搜到的同名点。从那以后我养成了一个习惯任何批量坐标数据交付前必须随机抽 30 条人工看一眼地图看不了就找业务方的样本地址反查。这三十条能挡掉八成事故比任何校验脚本都值。希望帮到你。本文还有配套的精品资源点击获取
简介面向物流配送、地图服务与区域统计分析等场景整理的中国行政区划邮编与经纬度数据集合覆盖省、市、区、县、乡、镇、街道层级共约46090条记录以结构化SQL表形式存放便于直接导入关系型数据库做查询、关联与二次开发。压缩包内共1个文件为SQL脚本整体约942KB字段可支撑按行政层级检索、坐标定位及区域划分等基础工作适合GIS入门者、后端开发与数据分析人员快速验证地址匹配、配送范围测算等需求。已有796人学习下载。数据以表格组织每行对应一个行政区域包含行政区名称、邮政编码及经纬度等字段可直接用于地图标注、物流路径优化、市场区域细分、政府规划参考和灾害响应定位配合SQL查询还能与人口、经济等指标关联形成更完整的区域分析底表减少从多源渠道拼装清洗坐标与邮编的成本。1. 五级行政区划带邮编和坐标难点从来不在“抓”而在“对”做门店选址、快递分单、区域报表的人迟早会撞上同一件事手里只有一串“省市区县乡镇街道”的文本系统要的却是能下钻、能定位、能算距离的结构化数据。于是就有了「全国省、市、区、县、乡、镇、街道邮编及经纬度坐标」这类需求——它本质是一张覆盖五级行政单元、每行带邮政编码和经纬度坐标的底表。听着像纯抓取的活真做下去会发现抓数据只占三成剩下七成是编码对齐、坐标系统一和边界核对。这篇把我自己做这套表的完整路径拆开数据源怎么挑、表怎么设计、地理编码怎么批量跑、坐标怎么验、哪几个地方必翻车。适合要自己维护一份地址底表的后端和数据同学也适合被“地址对不上”折磨过的业务开发。2. 数据源不能只挑一个行政区划代码、邮编、坐标该分别信谁先把一个错觉捅破不存在一个“全都对”的源。行政区划代码、邮政编码、经纬度坐标这三块数据的产生机制完全不同——代码是行政编制部门按区划调整发布的跟着撤县设区、撤乡并镇天天变邮编是邮政投递网络划定的范围跟行政边界根本不是一回事坐标是地图服务商按自己的采集和加密规则给出的点同一栋楼在不同平台能差出几百米。指望一个接口把三者一起吐出来最后一定是某个维度悄悄错了而你没发现。我一般的做法是三源并行、职责分离行政区划代码做骨架和主键邮编做附加属性且允许一对多坐标单独一张点位表按坐标系标注来源。三张表之间用行政区划代码串起来出了问题能定位到是哪一环错的而不是对着一张大宽表猜。这套思路在第一次做的时候会觉得麻烦等你遇到第二次区划调整就知道省了多少返工。2.1 五级代码的位数规则6 位、9 位、12 位分别锁住哪一级行政区划代码不是一串随便的数字它是有严格分段含义的。最常见的是 6 位码前 2 位是省级、中间 2 位是地级、后 2 位是县级省级码的后四位补零地级码的后两位补零。这套 6 位规则是绝大多数业务系统里“地区表”的基础。但 6 位码到县级就断了街道乡镇这一层要往上加 3 位变成 9 位村和社区再加 3 位变成 12 位。所以如果你要做“省市区县乡镇街道”五级实际用到的是 6 位和 9 位两套如果还想下钻到村居就得用 12 位。这三套码之间是前缀包含关系12 位码的前 9 位一定是它所属的乡镇码前 6 位一定是它所属的区县码——这个性质是做层级还原的全部依据。层级代码位数分段含义补零规则典型用途省级2 位有效 / 6 位前 2 位后 4 位为 0大区统计、报表分组地级4 位有效 / 6 位前 2 中 2后 2 位为 0城市维度聚合县级6 位前 2 中 2 后 2无地址主键、区县下钻乡级9 位6 位 3 位无街道乡镇派单、网格村级12 位9 位 3 位无末端配送、社区治理注意最后一行村级码虽然存在但它的更新频率和可获得性远不如前四级很多公开数据只到乡级。如果你的业务不需要村居粒度就别贪多把 9 位作为最小粒度维护成本会低一个量级。还有一个容易被忽略的点省级码里有一批“特殊段”比如直辖市、自治区、以及省直辖的县级行政单元。省直辖县级市在 6 位码里的位置是“省级码 90 左右的段 县级码”它没有地级父节点。如果你按“前 4 位当地级”去硬拆这类单元会被解析成一个不存在的市后面所有层级都错位。处理方式是在层级字段里显式标记一个“省直辖”类型还原父子关系时走特判分支而不是靠位数硬切。2.2 邮政编码是投递范围不是行政范围别拿它当外键邮编是 6 位数字结构上大致是“前 2 位大区、第 3 位省、第 4 位邮区、后 2 位投递局”。看起来像层级实际上它描述的是一套投递网络跟行政区划是两套并行的划分体系两者只在大部分时候重合在边界地带经常打架。最典型的三种不一致一个区县横跨多个邮编比如城区和下面的乡镇邮编不同一个邮编覆盖多个区县尤其是城区密集地带几个区的部分街道共用一个投递局街道乡镇这一级邮编基本不可靠很多街道根本没有独立邮编只能沿用上级区县的码。所以如果你把邮编当主键、或者做“邮编 → 区县”的反查表一定会在边界数据上翻车。我的处理是把邮编放在一个独立的关联表里一对多主表只保留一个“代表邮编”用于展示实际分单、路由一律以行政区划代码为准。代表邮编的选取规则也很简单优先取区县主城区对应的那个码取不到就取该区县下出现频次最高的码并在字段里标注是“精确”还是“继承”。这个标注看着多余等到业务方拿着邮编投诉“为什么我这条地址邮编不对”时你就知道它有用了。需要提醒的是邮编本身在逐年弱化快递分单早就以“省市区 详细地址 末端网点”为主邮编更多是报关、传统信函和部分政务表单的要求。所以这块的数据精度做到区县级就够用不必死磕街道级邮编——那是个投入产出比极低的坑。2.3 建表一张能同时扛住五级下钻和点位查询的表表设计的核心决策是“宽表还是分层表”。宽表查询快、导出方便但坐标一改就得整行更新而且一个行政单元可能有多个点位政府驻地、辖区中心、几何质心宽表塞不下。分层表灵活但每次下钻都要递归。我最终的方案是折中一张行政区划主表存层级和名称一张点位附表存坐标邮编走单独的关联表。CREATE TABLE admin_division ( adcode VARCHAR(12) NOT NULL COMMENT 行政区划代码9位或12位, parent_code VARCHAR(12) NOT NULL DEFAULT COMMENT 父级代码省级为空串, level TINYINT NOT NULL COMMENT 1省 2地级 3县级 4乡级 5村级, div_type TINYINT NOT NULL DEFAULT 0 COMMENT 0普通 1直辖市 2省直辖县级 3开发区/新区, name VARCHAR(64) NOT NULL COMMENT 标准全称, short_name VARCHAR(32) NOT NULL DEFAULT COMMENT 简称用于地址拼接, full_path VARCHAR(255) NOT NULL DEFAULT COMMENT 省/市/区/乡 拼接路径, is_active TINYINT NOT NULL DEFAULT 1 COMMENT 1有效 0已撤销, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (adcode), KEY idx_parent (parent_code), KEY idx_level_name (level, name) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT行政区划主表; CREATE TABLE admin_point ( id BIGINT NOT NULL AUTO_INCREMENT, adcode VARCHAR(12) NOT NULL, point_type TINYINT NOT NULL COMMENT 1政府驻地 2几何质心 3地图POI命中点, lng DECIMAL(10,6) NOT NULL COMMENT 经度, lat DECIMAL(10,6) NOT NULL COMMENT 纬度, coord_sys VARCHAR(16) NOT NULL COMMENT WGS84 / GCJ02 / BD09, source VARCHAR(32) NOT NULL COMMENT 数据来源标识, confidence TINYINT NOT NULL DEFAULT 3 COMMENT 1高 2中 3低, PRIMARY KEY (id), KEY idx_adcode_type (adcode, point_type) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT行政单元点位附表; CREATE TABLE admin_postcode ( adcode VARCHAR(12) NOT NULL, postcode CHAR(6) NOT NULL, match_level TINYINT NOT NULL COMMENT 1精确到该单元 2继承自上级, PRIMARY KEY (adcode, postcode) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT邮编关联表;这三张表的取舍逻辑值得说清楚。adcode用 VARCHAR 而不是 INT因为代码里有前导零省码“11”存成 INT 会变成 11拼前缀时补零补错一位就全错level和div_type分开而不是合并是因为“省直辖县级”这种单元既要标层级又要标特殊类型合在一个字段里查询会很难写admin_point里coord_sys这个字段是必须的没有它你就分不清这条坐标能不能直接和业务里的 GPS 坐标算距离。full_path是个冗余字段用空间换时间。地址拼接、模糊搜索、导出报表都靠它否则每次都要递归五层。代价是任何一级改名都要级联更新所以我在数据同步流程里加了一步“改名检测”对比新旧快照只要有 name 变化就批量刷新该节点及其所有子孙的full_path。这一步不做线上就会出现“父级叫新名、子级路径里还是旧名”的诡异数据。confidence这个字段在后期排错时价值极高。同样一个街道来自官方代码库的坐标和来自地图 POI 搜索的坐标可信度差得很远。把置信度写进表里做距离校验时就能只对低置信度的记录做人工复核而不是全量重跑。3. 把五级拉平成一张宽表代码解析、层级重建与边界校验拿到原始代码列表之后第一件事不是入库是还原层级。很多公开数据下发的是扁平列表一条条记录带着自己的代码和名称但父子关系要么没给要么给的是“父级名称”这种不可靠字段——因为名称会重名。第一章说过 12 位码有前缀包含性质这就是免费的父子关系比自己猜要稳得多。3.1 用前缀法还原父子关系顺手把省直辖单元挑出来前缀法的实现很直接对每个 9 位或 12 位码按位数规则截取上级码再去全量集合里查是否存在。存在就挂上不存在就说明上级缺失或者这个节点属于特殊类型。这段逻辑我写成了一个可反复跑的函数每次数据更新都全量重建一遍父子关系不做增量因为增量维护父子指针在区划调整时几乎必错。from collections import defaultdict # 各级别对应的代码长度键是子级值是父级 PARENT_LEN {12: 9, 9: 6, 6: 4, 4: 2} def resolve_parent(adcode: str, all_codes: set) - str: 按位数规则向上找父级找不到返回空串 code adcode.rstrip() for cur_len, parent_len in PARENT_LEN.items(): if len(code) cur_len: # 6位码里省级是后4位为0地级是后2位为0要区分 if cur_len 6: if code.endswith(0000): return if code.endswith(00): return code[:2] 0000 return code[:4] 00 parent code[:parent_len].ljust(len(code), 0) return parent if parent in all_codes else return def build_tree(rows: list) - list: rows: [{adcode: 110101001001, name: 某居委会}, ...] 返回补全 parent_code / level / div_type 的记录 all_codes {r[adcode] for r in rows} out [] for r in rows: code r[adcode] parent resolve_parent(code, all_codes) level {2: 1, 4: 1, 6: 3, 9: 4, 12: 5}.get(len(code), 5) # 6位码单独判层级 if len(code) 6: if code.endswith(0000): level 1 elif code.endswith(00): level 2 else: level 3 div_type 0 if level 2 and code[:2] in (11, 12, 31, 50): div_type 1 # 直辖市 if level 3 and not parent: div_type 2 # 省直辖县级无地级父节点 out.append({**r, parent_code: parent, level: level, div_type: div_type}) return out这里的逻辑说明几点。ljust是用来给父级码补零的因为截断之后的父级码长度不够必须补到和原码一样的位数才能在集合里匹配上——比如 12 位码截前 9 位得到 9 位父码本身长度就对了但如果从 9 位往 6 位找截前 6 位得到的就是 6 位不需要补真正需要补的是省级这种“2 位有效 4 位零”的情况所以我在 6 位分支里单独写了判断而不是靠ljust硬补。div_type的判断是这套代码里最容易被砍掉、又最不能砍的部分。直辖市在 6 位码里是“省级码 0000”它下面直接挂区没有地级这一层如果按常规四级结构去还原会得到一条“直辖市 → 某区”的父子对但level会算成 1 和 3中间缺了一层前端做三级联动时就会断。省直辖县级市同理它挂不到任何地级父节点上parent返回空串如果不打标入库时会被当成数据缺失给过滤掉。跑完这一步level分布应该是一个稳定的金字塔省级三十多个地级三百多个县级两千八百多个乡级四万多个。如果某一级的数量明显偏离这个量级不用怀疑一定是父级还原出问题了回头查代码格式——最常见的是原始数据里混进了 6 位码和 9 位码两种粒度被当成同一批处理。3.2 街道级数据补齐的两条路官方代码库与地图 POI 的偏差县级以上的数据相对好拿街道乡镇这一层才是分水岭。我的经验是走两条路互相兜底官方发布的统计用区划代码作为权威骨架保证“有哪些街道、代码是什么”不出错地图服务商的 POI 搜索结果用来补坐标和纠正常见别名保证“这个街道在哪”有落点。权威骨架的价值在于完整性。它给出的街道列表是穷举的不会漏缺点是更新有滞后——某地新设了一个街道代码库里可能半年后才出现。地图 POI 的价值在于时效性和坐标缺点是召回不稳定搜“某某街道”可能返回街道办事处、可能返回同名社区、也可能返回一个商圈名甚至返回隔壁县的同名街道。所以补齐流程我是这么设计的先以权威骨架为准建全量节点然后用“省 市 区 街道名”拼成查询串去地图侧取点位取回来的结果必须过两道过滤——一是行政区划包含校验点位必须落在上级区县的边界内二是名称相似度校验返回名称要包含街道名的主体部分。两道都过才写入point_type3、confidence2只过一道的进待复核队列一道都不过的直接丢弃宁缺毋滥。这里有个反直觉的结论街道级坐标的准确率瓶颈不在接口质量在名称规范度。同一个街道官方叫“某某街道办事处”地图上叫“某某街道”民间叫“某某”三种写法搜出来的结果差别很大。我在清洗阶段会把“街道办事处”“办事处”“街道”这几个后缀统一剥离只留主体名再拼上级行政区去搜命中率和准确率都能明显提升。这个细节后面第 4 章还会展开。3.3 自动挑脏数据三类校验规则和对应处置数据入库不等于可用还得有一层校验把脏数据挑出来。我固定跑三类规则跑完输出一份异常清单人工只看清单不看全量。第一类是层级完整性校验每个非省级节点必须有父节点每个节点的level必须等于父节点level 1唯一例外是div_type1的直辖市和div_type2的省直辖县级。这条规则能抓出 90% 的解析错误。第二类是名称重复校验同一父节点下不允许同名子节点跨父节点同名是正常的全国重名的镇非常多但要在表里留一个“同名组”标记供后续地理编码时做区分。这条规则抓的是数据源混入了重复行。第三类是坐标越界校验每个点位的坐标必须落在其上级区县的几何边界内或者至少落在上级地级市的边界内。没有边界数据的话退化成一个粗略的矩形框校验也行——用上级节点的中心点和半径做一个缓冲区超出缓冲区的标记为可疑。这条能抓出地理编码串到外省的情况实测抓得挺准。def check_coord_in_bbox(lng, lat, center_lng, center_lat, radius_km80): 粗略的矩形框校验radius_km 按地级市尺度取 60~100 # 纬度 1 度约 111km经度按当前纬度收缩 import math dlat radius_km / 111.0 dlng radius_km / (111.0 * math.cos(math.radians(center_lat)) 1e-9) return (abs(lng - center_lng) dlng) and (abs(lat - center_lat) dlat)radius_km这个参数要按层级调县级用 30 到 50地级用 80 到 120。设太小会把辖区边缘的正常点位误判成异常设太大又抓不住串区。我的做法是先按 80 跑一遍看异常率如果超过 5% 就把半径放宽一档再跑反复两次基本能定到一个合适的值。这套阈值没有普适解得按你数据的实际分布调别人的参数抄过来大概率不合用。4. 批量取经纬度输入清洗、限流重试和坐标系统一到这一步骨架有了、点位缺了剩下的活是把几万个街道名批量换成坐标。听起来是调接口的体力活实际上三个地方决定成败查询串怎么拼、失败怎么分类重试、坐标回来之后怎么统一。4.1 输入侧清洗把“某某街道”拼成能被地理编码命中的地址串地理编码接口对输入格式非常敏感。直接拿“某某街道”去搜返回的可能是同名的省外节点拼成“省 市 区 某某街道”命中率立刻上一个台阶。但拼接本身也有讲究拼错了反而降低命中率。第一个讲究是行政区名称要用“标准简称”而不是“全称”。全称里带“省”“市”“区”“自治县”这些后缀接口做分词时会切得很碎用简称则更接近人们日常表达的地址。所以我建表时留了short_name字段专门用于地址拼接比如全称去掉末尾的行政后缀。少数民族自治地方的名称有特殊性不能简单截断得单独维护一个小映射表。第二个讲究是街道名的后缀处理。前面提过“某某街道办事处”要剥成“某某”但剥离之后要去重——有些地方存在“某某街道”和“某某镇”同名的情况剥完就撞了。撞名的情况下保留原始后缀让接口自己判断。第三个讲究是拼接顺序和分隔符。我统一用“省简称 市简称 区县简称 街道名”中间不加空格不加逗号因为大多数接口对连续中文字符串的处理最稳。加了逗号反而可能被当成多段地址分别解析。SUFFIX_MAP {省: , 市: , 区: , 县: , 自治县: , 旗: } def clean_name(full_name: str, keep_suffix: bool False) - str: 剥离行政后缀keep_suffix 用于重名场景 if keep_suffix: return full_name for suf in (街道办事处, 办事处, 街道, 镇, 乡): if full_name.endswith(suf) and len(full_name) len(suf): return full_name[:-len(suf)] return full_name def build_query(row: dict, parent_map: dict) - str: row 需要含 adcode/nameparent_map 是 adcode - 记录 的字典 parts [] cur row while cur: parts.append(clean_name(cur.get(short_name) or cur[name])) cur parent_map.get(cur.get(parent_code)) parts.reverse() parts.append(clean_name(row[name], keep_suffixTrue)) return .join(parts)build_query是从当前节点一路往上走到省级把各级简称收集起来再反转最后把本节点的名字带后缀方便接口区分街道和镇追加到末尾。这样拼出来的串形如“某省某市某区某某街道”没有多余字符。keep_suffix这个开关就是为重名场景准备的先跑一遍全量把所有拼出来的串做一次去重统计撞名的那些记录标记出来第二次跑时把这批改成keep_suffixTrue重试。实测撞名比例大概在 1% 到 3% 之间主要是“某某镇”和“某某街道”并存的地方以及部分历史沿革导致的同音不同字。4.2 并发、限流和失败分类重试不能一把梭批量跑接口必须有并发控制但并发数不是越高越好。多数公开地理编码服务的配额是按 QPS 计的超了直接返回限流错误而你如果把这当成普通失败去重试只会把配额烧得更快。我的做法是三层控制并发数固定在一个保守值请求之间加固定间隔失败按错误码分类处理。分类是关键。网络超时和 5xx 归为“可重试”退避时间按指数增长4xx 里的参数错误归为“不可重试”直接记失败原因限流错误单独一类遇到就整体降速并把当前批次打回去重跑。如果不做这个分类一律重试三次最后的失败率会虚高而且日志里全是同一种错误根本看不出真实原因。import time, random from collections import Counter RETRY_BACKOFF [1, 3, 9] # 三次重试的等待秒数 QPS_INTERVAL 0.12 # 单请求最小间隔约 8 QPS def fetch_with_retry(session, url, params, stats: Counter): for attempt in range(len(RETRY_BACKOFF) 1): time.sleep(QPS_INTERVAL random.uniform(0, 0.03)) try: resp session.get(url, paramsparams, timeout5) except Exception as e: stats[timeout] 1 if attempt len(RETRY_BACKOFF): time.sleep(RETRY_BACKOFF[attempt]) continue return None, timeout if resp.status_code 200: body resp.json() if body.get(status) ok and body.get(result): stats[ok] 1 return body[result], None stats[empty] 1 return None, empty if resp.status_code 429: stats[rate_limited] 1 time.sleep(RETRY_BACKOFF[min(attempt, 2)] * 2) continue if 500 resp.status_code 600: stats[server_err] 1 time.sleep(RETRY_BACKOFF[attempt]) continue stats[client_err] 1 return None, fhttp_{resp.status_code} return None, retry_exhaustedQPS_INTERVAL这个值要按你拿到的配额倒推配额是 10 QPS就把间隔设在 0.12 秒左右留一点余量。RETRY_BACKOFF用 1、3、9 三档是因为大多数限流窗口是按秒或分钟计的等 9 秒基本能跨过窗口。status empty单独统计很重要——它代表接口通了但没搜到结果属于数据问题不是网络问题这部分记录要回流到清洗环节重新拼查询串而不是继续重试。跑完之后看stats的分项ok占比低于 85% 就说明输入清洗有问题empty占比高通常是后缀处理或简称映射错了rate_limited占比高就把间隔调大。这套指标比“总成功率”有用得多。4.3 坐标系统一GCJ-02、WGS84、BD-09 混用是最隐蔽的错坐标回来之后最容易埋雷的地方来了。国内主流的互联网地图服务给出的坐标大多是在 WGS84 基础上做过非线性偏移的 GCJ-02还有一类厂商用自己的二次偏移坐标系业内常称 BD-09。而 GPS 设备、北斗模块、大部分开源地理数据给的是标准 WGS84。这三套坐标如果不加区分地混在一张表里算出来的距离能差几百米而且偏差不是固定值随经纬度变化——这就是它最坑的地方你没法用一个固定偏移量修正。我的铁律是入库必标coord_sys跨系计算前必转。转换只做两件事——GCJ-02 与 WGS84 互转以及 GCJ-02 与厂商私有坐标系互转。前者的算法是公开的后者通常就是在 GCJ-02 上再做一次固定公式变换。import math A 6378245.0 EE 0.00669342162296594323 def _out_of_china(lng, lat): return not (73.66 lng 135.05 and 3.86 lat 53.55) def _transform_lat(x, y): ret -100.0 2.0*x 3.0*y 0.2*y*y 0.1*x*y 0.2*math.sqrt(abs(x)) ret (20.0*math.sin(6.0*x*math.pi) 20.0*math.sin(2.0*x*math.pi)) * 2.0/3.0 ret (20.0*math.sin(y*math.pi) 40.0*math.sin(y/3.0*math.pi)) * 2.0/3.0 ret (160.0*math.sin(y/12.0*math.pi) 320*math.sin(y*math.pi/30.0)) * 2.0/3.0 return ret def _transform_lng(x, y): ret 300.0 x 2.0*y 0.1*x*x 0.1*x*y 0.1*math.sqrt(abs(x)) ret (20.0*math.sin(6.0*x*math.pi) 20.0*math.sin(2.0*x*math.pi)) * 2.0/3.0 ret (20.0*math.sin(x*math.pi) 40.0*math.sin(x/3.0*math.pi)) * 2.0/3.0 ret (150.0*math.sin(x/12.0*math.pi) 300.0*math.sin(x/30.0*math.pi)) * 2.0/3.0 return ret def wgs84_to_gcj02(lng, lat): if _out_of_china(lng, lat): return lng, lat dlat _transform_lat(lng - 105.0, lat - 35.0) dlng _transform_lng(lng - 105.0, lat - 35.0) radlat lat / 180.0 * math.pi magic math.sin(radlat) magic 1 - EE * magic * magic sqrtmagic math.sqrt(magic) dlat (dlat * 180.0) / ((A * (1 - EE)) / (magic * sqrtmagic) * math.pi) dlng (dlng * 180.0) / (A / sqrtmagic * math.cos(radlat) * math.pi) return lng dlng, lat dlat def gcj02_to_wgs84(lng, lat): 一次迭代反解精度足够业务使用 glng, glat wgs84_to_gcj02(lng, lat) return lng * 2 - glng, lat * 2 - glat这几个函数里_out_of_china的边界判断不能省境外坐标不应该做偏移否则会把正常数据改坏。gcj02_to_wgs84用的是“正算两次取差”的近似反解误差在米级做区域统计、距离排序完全够用如果要做高精度测绘得换成迭代反解但那已经超出这类业务表的范围了。实际使用时还有一条经验转换之后的坐标要写回表并更新coord_sys不要每次查询时实时算。实时算的问题是同一个点在不同代码路径里可能被转两次转两次的偏差会累积而且是那种查不出来的玄学偏差——数据看着都对就是算出来的距离不对。这个坑我踩过一次排查了整整两天最后发现是某个导出任务多转了一道。5. 避坑与排查五级地址表上线前最容易翻车的五个地方下面这几条都是从翻车现场攒下来的每条按“现象、原因、解决”写遇到的时候直接对号入座就行。第一条某批区县的街道数据整批为空日志里没有任何报错。现象是跑完之后发现某些区县下面一个乡级节点都没有但接口调用记录显示成功。原因通常有两个一是这些区县在原始数据里用 6 位码给了没有下钻到 9 位脚本按 9 位找自然找不到二是这些区县是近年新设的坐标系和代码库版本对不上。解决方式是加一步“覆盖率检查”——按level3遍历所有区县统计其下level4的节点数为 0 的直接进异常清单。这个检查一定要放在流程里不能靠人眼扫。第二条地理编码返回的坐标落在隔壁省距离差几百公里。现象是抽样看坐标明显不在本省范围内。原因是查询串拼得太短比如只用了“某某镇”而全国重名的镇有几十个接口按热门度返回了另一个。解决办法前面说过拼接必须带完整上级路径另外加一道边界校验作为最后防线超出上级地级市缓冲区的一律打回重查。血泪经验是边界校验的阈值宁紧勿松误判成异常的记录看一眼就能确认漏判成正常的记录可能几个月都没人发现。第三条同一个街道附表和主表里的坐标差了十几公里。原因是点位类型混用——街道办事处驻地和辖区几何质心是两个完全不同的点前者往往偏在辖区一角后者在中心。如果业务算服务半径用驻地会严重低估覆盖范围。解决方式是在附表里用point_type严格区分业务查询时显式指定要哪一种不要写“取任意一条”。默认规则我定的是算距离用几何质心做行政中心展示用政府驻地两个都缺才退回 POI 命中点。第四条直辖市和省直辖县级市在三级联动里断档。现象是前端选完省之后市这一级是空的或者跳过了。原因就是第 3 章说的这类单元的层级结构和常规不一样如果前端按“省 → 市 → 区”硬套三级中间那级取不到值。解决方式是在接口层做一次扁平化对于div_type1或2的节点直接返回“省级 区县”两级前端的联动组件要支持“动态层级”——即某一级可以跳过。这个改动不大但必须在设计阶段就定下来等前端写完再改成本很高。第五条邮编和行政区划对不上业务方反复来问。现象是某条地址的邮编和区县不匹配但查下来两边数据都没错。原因是邮编更新滞后于区划调整或者该地本来就一个邮编覆盖多个区。解决方式不是修数据是修预期在接口返回里把match_level带出去明确告诉调用方这个邮编是精确到该单元的还是从上级继承来的。承接方看到“继承”就知道不该拿它做主键。这条说起来是产品沟通问题实际是数据表设计问题——当初没留这个字段后面就只能一遍遍解释。这五条之外还有一类不算坑但要提前想清楚的事数据更新频率。区划调整每年都有频率不高但影响面大。我的做法是每季度全量同步一次同步时保留历史快照用is_active标记撤销节点而不是物理删除。物理删除的后果是历史订单里的老地址关联不到节点报表直接出现空洞那时候想补都补不回来。6. 坐标精度怎么验距离抽检、边界包含和一份可复用的验收脚本数据跑完不等于能交付还得有一套能量化的验收。我常用的三个手段从粗到细依次是距离抽检、边界包含校验、以及与已知参照点比对。距离抽检最省事随机抽一批乡级节点算它的点位到其上级区县几何质心的距离按地级市尺度设一个上限比如 80 公里超出的挑出来人工看。这个方法能抓住明显的串区错误。参数上不要把上限设得太死山区和面积大的县很容易正常超限我一般先按 100 公里跑看异常率再逐步收紧。边界包含校验更严格需要区县级的边界数据。做法是用射线法判断点位是否落在多边形内落在外面的标记可疑。边界数据可以从公开的地理信息数据集拿精度做到县级就够。这个方法的误报主要来自边界简化——简化后的多边形和真实边界有几十米差异边缘点位会被误判所以判定为“外”的点位要再用距离阈值兜一层距边界 1 公里以内的不报。def ray_casting(lng, lat, polygon): polygon: [(lng, lat), ...] 闭合或非闭合均可 inside False n len(polygon) j n - 1 for i in range(n): xi, yi polygon[i] xj, yj polygon[j] if ((yi lat) ! (yj lat)) and \ (lng (xj - xi) * (lat - yi) / (yj - yi 1e-12) xi): inside not inside j i return inside def point_to_segment_km(p, a, b): 点到线段的最短距离单位公里用于边界容差判断 import math lng, lat p ax, ay a; bx, by b dx, dy bx - ax, by - ay if dx 0 and dy 0: return math.hypot(lng - ax, lat - ay) * 111.0 t ((lng - ax) * dx (lat - ay) * dy) / (dx*dx dy*dy) t max(0.0, min(1.0, t)) cx, cy ax t*dx, ay t*dy return math.hypot(lng - cx, lat - cy) * 111.0ray_casting是标准射线法注意分母加了1e-12防止水平边除零。point_to_segment_km用来算点到边界的最短距离判定在边界外但距离小于 1 公里的不报异常。这个容差参数按你边界数据的简化精度调简化得越狠容差要越大。第三个手段是与参照点比对。找一批确定无疑的点位——比如各省级行政中心、几个大城市的标志性地点——把你的表里对应的坐标和参照坐标算距离超过阈值的说明坐标系转错了。这个方法主要用来验证第 4 章那套转换函数有没有用对上下误差应该在 50 米以内超过就是转错方向或者多转了一次。验收的产出不是一篇文章是一份异常清单加三个比例覆盖率、越界率、抽检偏差中位数。覆盖率低于 95% 说明缺数据越界率高于 2% 说明地理编码有问题偏差中位数超过 200 米说明坐标系或者点位类型选错了。这三个数字卡住数据基本就能交付。我自己最常犯的错是把“跑通了”当成“跑对了”。第一次做这套表的时候脚本一把过、几万条记录全绿我直接发了结果业务方拿去算门店覆盖发现郊区的乡镇全被算到市区去了。后来才知道那批乡镇的坐标是地理编码按“某某镇”搜到的同名点。从那以后我养成了一个习惯任何批量坐标数据交付前必须随机抽 30 条人工看一眼地图看不了就找业务方的样本地址反查。这三十条能挡掉八成事故比任何校验脚本都值。希望帮到你。本文还有配套的精品资源点击获取
