简介面向需要批量获取地址经纬度的 Python 开发者一套基于高德地图 API 的可运行项目源码覆盖环境配置、API 密钥申请、地理编码请求、坐标系统转换与数据输出等完整流程可帮助快速搭建批量地理编码工具。资源包共 9 个文件以 6 个 Python 脚本为核心分别实现地理编码请求、坐标转换、Excel 模板生成等功能另含 Excel 输入输出模板和 HTML 说明页整体仅 15KB轻量便携。已有 135 人学习下载适合中初级开发者及需要批量处理地理编码数据的技术人员参考。源码中 gaode.py 负责发送地理编码请求并解析返回的经纬度convers.py 处理坐标系转换create_input_excel.py 可快速生成标准输入格式配合 pandas 读写 Excel实现从地址列表到经纬度结果的自动化处理。同时脚本模块划分清晰提供从简单示例到最终版实现的递进参考并附带文件权限等常见问题排错思路可直接扩展用于数据分析、地图可视化等场景。1. 高德API批量获取经纬度一张地址表到一张坐标表的最短路做地图可视化或门店经营分析时手头往往是几百上千条中文地址没有经纬度。要把这些地址画到图上最直接的办法就是调高德地图API的地理编码接口把「地址字符串」转换成「经纬度坐标」。这个需求的难点从来不在单条调用而在批量场景下的配额控制、并发限速和数据质量直接拿 for 循环硬跑几千个地址中途很容易触发限流甚至静默失败。这篇笔记写给两类人一类是刚接触地理编码、想把自己手里的地址表变成坐标表的新手另一类是已经跑通过单条调用、但批量结果总是不全想搞清城市字段、请求频率和坐标系这些细节的从业者。下面会把批量实现思路、参数取舍和最容易踩的坑一起讲完代码可以直接照抄调整。2. 地理编码接口与Key选型先跑通单条请求再谈批量我的习惯是先手工验证单条请求再写批量脚本。直接上循环一旦出错很难定位是网络问题、地址问题还是频率问题。地理编码接口本身很简单难点集中在选型与参数理解。这里先把接口方向、Key类型和参数讲清楚为后面的批量脚本打底。2.1 正向地理编码与逆地理编码别在接口方向选错高德Web服务里有两类地理编码能力。正向是把「地址文本」转成「经纬度」适用于把地址表落到地图上做撒点、热力、网格分析逆向是把「经纬度」反查成「地址描述」适合轨迹回放、车辆位置语义化这类场景。批量获取经纬度的任务应该用正向地理编码接口。两个接口的请求地址不同、参数不同、返回结构不同而且配额体系也不是一套。我见过有开发者把逆地理编码的地址填到批量脚本里请求参数对不上返回一堆参数错误排查了好久才发现方向都选反了。正向接口的请求方式是 GET核心入参是 address。服务端拿到地址文本后会做分词、行政区划匹配和候选排序返回一条或多条结果。我一般取结果数组里的第一项作为坐标同时也要留意返回数量。如果返回多条说明地址有歧义需要在请求里加 city 字段做限定。这个细节直接关系到批量命中率下一节展开说。2.2 城市字段与地址规范化批量命中的第一道门槛city 参数在官方说明里是选填但实际批量场景里我几乎必填。原因很简单国内重名地名太多了「某某路 188 号」可能在好几个城市同时存在解析器必须靠城市字段把候选范围缩小。city 传「某市」或「某区」都可以但最好和 address 里的行政区划表述保持一致不要让服务端去猜。批量前我一般会先把原始地址清洗一遍拼成「省市区街道门牌号」的形式。原始数据里如果只有「高新区永兴路 36 号」就利用数据里已有的城市列填充 city如果原始数据有省市区多列先拼接再请求。地址里的「靠近」「对面」「旁边」这类相对方位词建议去掉空格和换行也一定要清掉否则一个小空格就能让分词结果变样。核心参数我整理成一张表请求前先对照确认参数是否必填作用我的建议address必填待解析的地址文本按省市区街道门牌号拼接去掉口语化描述city选填限定城市或区缩小候选范围批量时建议带上尤其地址有重名嫌疑时key必填Web服务类型的高德Key不要用JS API的Key混调output选填返回格式json或xml脚本处理用 json 即可2.3 单条调用最小代码requests请求与返回结构说明单条调用我用 requests 直接打 HTTP 接口不依赖任何地图 SDK。这样脚本在任何环境里都能跑也方便替换成异步方案。下面是封装好的最小函数import requests def geocode(address, cityNone, key你的高德Web服务Key): # 正向地理编码地址转经纬度 params { address: address, key: key, output: json, } if city: params[city] city resp requests.get( https://restapi.amap.com/v3/geocode/geo, paramsparams, timeout8, ) data resp.json() # status1 代表请求成功不等于匹配成功 if data.get(status) ! 1: return None, data.get(info, unknown_error) geocodes data.get(geocodes) or [] if not geocodes: return None, no_result # 多条结果时取第一条需要更严谨可以结合城市字段二次过滤 location geocodes[0].get(location, ) return location, None逻辑说明status1 只说明请求链路通了并不代表地址一定匹配成功。geocodes 是匹配结果数组为空就是地址解析不到。location 字段是字符串「经度,纬度」顺序不要弄反后面解析成浮点数时也要注意。返回的第二个值携带错误原因这个设计是为了批量时能直接把失败原因写进日志。参数说明address 必填city 传空不会报错但结果可能不唯一timeout 给 8 秒网络波动时能快速失败重试key 不要硬编码在业务代码里建议放到环境变量或配置文件中。在线网页工具适合一次性几十条的小任务几百条以上就非常低效还容易复制错位自建脚本一次跑几千条中途失败可以定位这是我觉得更可靠的方式。3. 批量获取经纬度的主流程并发控速与结果校验单条请求跑通后其实已经把 70% 的工作做完了。剩下的是三件事把地址读进来、限速并发、把结果回写同时把失败的地址单独留下来。下面是我在做类似需求时常用的结构。3.1 地址表的来源与任务设计从CSV到任务队列管理几千条地址我一般用 CSV 而不是 Excel。openpyxl 处理大文件偏慢CSV 配合标准库读写稳定而且控制编码很容易。文件里最少保留三列id、address、city。city 列允许为空程序里用数据中已有的省份或城市信息兜底。读取时用 DictReader每行是一个字典后面传给请求函数很方便。import csv def load_tasks(csv_path): tasks [] with open(csv_path, encodingutf-8-sig) as f: reader csv.DictReader(f) for row in reader: # 地址列是必需的city列可以留空 if not row.get(address): continue tasks.append({ id: row.get(id, ), address: row[address].strip(), city: row.get(city, ).strip(), }) return tasks逻辑说明csv.DictReader 会按第一行表头自动生成字典比按列下标取值安全得多。编码用 utf-8-sig 而不是 utf-8是为了 Excel 打开生成的 CSV 时不出现中文乱码。address 做 strip 处理清除首尾空格避免同一个地址因为空格差异被判成两条任务。id 字段用于回写后对齐原始数据批量清洗时非常有用。3.2 线程池并发与全局最小间隔控制QPS不靠手写sleep地理编码是典型的无状态网络请求等待 IO 时 CPU 是闲着的用线程池可以显著提高吞吐。但同时要面对频率限制高德对单个 Key 有每秒并发限制不像本地脚本想跑多快跑多快。常见做法是线程池加一个全局锁控制任意两个请求之间的最小间隔。这比每个线程各自 sleep 更可控不会出现 8 个线程在同一秒同时打出去的情况。import time import threading import requests from concurrent.futures import ThreadPoolExecutor, as_completed MIN_INTERVAL 0.2 # 任意两个请求之间的最小间隔秒 MAX_WORKERS 8 # 并发线程数建议从 4 开始调 lock threading.Lock() last_call_time time.time() def rate_limited_request(params): global last_call_time with lock: # 计算距离上一次请求过去了多久不够则补齐等待 wait MIN_INTERVAL - (time.time() - last_call_time) if wait 0: time.sleep(wait) last_call_time time.time() resp requests.get( https://restapi.amap.com/v3/geocode/geo, paramsparams, timeout8, ) return resp.json()逻辑说明锁里做时间校验保证全局请求间隔不小于 MIN_INTERVAL。MAX_WORKERS 决定同时有多少个线程在等 IO间隔时间决定每秒最多发出多少请求。两个参数需要配合调线程开大了但间隔没变吞吐不会增加只会堆积排队间隔太小则可能触发限流。经验是从 0.2 秒间隔、4 线程开始跑 100 条看失败率再调整。参数说明MIN_INTERVAL 并不是越高越好它直接决定全量跑完的耗时。如果失败日志里出现频率限制相关提示优先加大间隔如果一切正常再逐步缩小到 0.1。MAX_WORKERS 不要一开始就开到 50线程多了 DNS 解析和连接建立也会成为瓶颈8 到 16 已经覆盖绝大多数场景。3.3 结果回写与失败日志数据完整性要单独保障并发请求完成后需要把结果统一收集按原顺序回写失败的单独落盘。很多批量脚本只写成功结果失败地址直接丢弃最后统计时发现少了几百条还不知道去哪了。我的习惯是建两个文件result.csv 存成功坐标failed.csv 存失败地址和失败原因。这样不管是补跑还是复查都有据可依。def process_task(task): params { address: task[address], key: KEY, output: json, } if task[city]: params[city] task[city] data rate_limited_request(params) if data.get(status) ! 1: return task, None, data.get(info, unknown_error) geocodes data.get(geocodes) or [] if not geocodes: return task, None, no_result location geocodes[0].get(location, ) return task, location, Nonewith open(result.csv, w, newline, encodingutf-8-sig) as rf: with open(failed.csv, w, newline, encodingutf-8-sig) as ff: result_writer csv.writer(rf) failed_writer csv.writer(ff) result_writer.writerow([id, address, location]) failed_writer.writerow([id, address, city, reason]) with ThreadPoolExecutor(max_workersMAX_WORKERS) as executor: futures {executor.submit(process_task, task): task for task in tasks} for future in as_completed(futures): task, location, error future.result() if location: result_writer.writerow([task[id], task[address], location]) else: failed_writer.writerow([task[id], task[address], task[city], error])逻辑说明process_task 把请求逻辑收敛成一个纯函数返回「任务、坐标、错误原因」三元组方便统一处理。as_completed 按完成顺序取结果不会阻塞等待最慢的那一个。失败原因被原样写进 CSV后面排查时看 reason 列就能知道是网络错误还是没匹配到地址。failed.csv 里保留 city 字段很重要补跑时可以直接复用不需要重新拼接输入数据。注意失败地址单独落盘是个非常值得养成的小习惯。补跑时只需要读取 failed.csv 再走一遍请求而不是把全量地址重新跑一遍能省下大量配额和时间。4. 批量翻车排查Key无效、结果为空与坐标偏移代码写完之后真正的考验才开始。以下 4 个坑是我在批量地理编码里经常遇到的也是排查时最先要确认的几件事。每一条按「现象、原因、解决」展开。4.1 INVALID_USER_KEYKey类型申请错不是Key过期现象控制台里明明能看到 Key单条请求在网页调试工具里也能通但脚本里一跑就返回 INVALID_USER_KEY。很多人的第一反应是换一个 Key 再试结果换了还是同样报错。原因高德控制台里的 Key 分了多种服务类型。调 Web 服务接口必须使用「Web服务」类型的 Key如果用 JS API 的 Key 去调 HTTP 接口就会报这个错。网页调试工具里可能自动帮你选择了匹配的类型所以能通脚本里没有这层处理问题就暴露了。解决在控制台重新创建一个「Web服务」类型的 Key替换代码里的 key 变量问题基本立刻消失。顺便检查一下这个 Key 是否绑定了 IP 白名单如果有绑定确认当前运行脚本的服务器 IP 在白名单内。很多人在这里卡住其实不是 Key 失效而是服务类型选错了。4.2 geocodes为空数组城市字段缺失让解析器无从下手现象status1 返回成功但 geocodes 是空的。同一个地址放到网页调试里却偶尔能出结果让人怀疑是代码问题。原因status1 本来就只代表请求成功并不保证地址匹配成功。address 指向一个泛化描述或者缺少 city 限定解析器无法确定它在哪个城市。尤其当原始地址只写到「永兴路 36 号」这种程度时候选范围横跨多个省份返回空就是很正常的结果。解决把省市区信息拼进 address同时显式传 city 字段。例如地址改成「某市高新区永兴路 36 号」city 传「某市」。如果数据里有更精细的区划city 传「某区」更好。对于确实解析不到的地址保留原始文本记录到 failed.csv不要手工改掉原文等人工复核后再决定是否补录。高德解析不到不代表地址不存在很多时候只是文本不规范。4.3 跑到一半开始连续失败QPS配额被打满后的降速策略现象前 300 条一切正常后面突然开始大面积失败失败原因集中在频率限制或配额相关提示。程序并没有崩网络也正常就是连续失败。原因单个 Key 的配额和并发限制触顶了。线程池并发跑得欢短时间请求量超过了限制服务端开始拒绝请求。这时候继续重试只会让限制时间拉得更长不会有任何好转。解决先停掉脚本把线程数降到 1MIN_INTERVAL 拉大到 1 秒以上让请求频率回落到安全区间。等一段时间后读取 failed.csv 里的地址做断点续跑。如果业务量长期比较大就把全量数据拆成几个时间段分批跑或者准备多个 Key 做轮询。这里一定要看失败日志凡是失败原因明确的不要盲目重试。4.4 坐标位置偏移GCJ-02坐标系与地址语义偏差现象坐标拿到了画到地图上却发现和实际位置差了上百米。有时候偏差不大但有规律地偏向某个方向。原因两个因素叠加。高德返回的坐标是 GCJ-02 坐标系也就是俗称的「火星坐标系」和 GPS 设备直接采集的 WGS-84 坐标之间存在非线性偏移。另外正向地理编码有时匹配到的是道路几何点而不是 POI 中心点这种语义偏差也会让坐标落在路边或区域中心而不是真正的门牌位置。解决如果展示层用的是高德底图直接使用返回坐标即可不需要做任何转换。如果必须转成 WGS-84 供其他系统使用需要使用公开的 GCJ-02 转 WGS-84 近似算法转换后做四舍五入但不要期望完全对齐。工程上一定要把坐标系来源标注清楚否则下游用错坐标系问题会跑很远才被发现。5. 把限速和失败重试做进同一个调度更稳的批量循环5.1 断点续跑与抽样核对批量任务收尾的两件小事批量地理编码的最后一公里我会把两个能力加进主循环跳过已完成地址、校验坐标是否在合法范围内。这两个小功能单独看不起眼放在批处理里能省掉很多重复劳动。import csv import os def check_location(loc): # 高德坐标范围经度约73~135纬度约18~53 if not loc: return False try: lon, lat map(float, loc.split(,)) except ValueError: return False return 73 lon 135 and 18 lat 53 already_done set() if os.path.exists(result.csv): with open(result.csv, encodingutf-8-sig) as f: for row in csv.DictReader(f): already_done.add(row[address])主循环里加判断当前地址在 already_done 中就跳过请求返回坐标后先用 check_location 过一次不符合范围直接按失败处理。这两步放在同一个循环里比单纯追求并发更有价值——至少不会再因为脚本中断把几万条地址重新跑一遍。验证方法也简单每次批量结束后随机抽 20 条地址在高德地图里手动核对坐标是否落在目标位置周边。做一次全量跑通并不难真正考验人的是批量结果能不能直接交给下游。我后来凡是做批量地理编码都会先把失败清单的落盘逻辑写好再开跑这个习惯省下的时间比任何并发优化都多。希望帮到你。本文还有配套的精品资源点击获取