星期一的活最难干。刚打开电脑业务那边就丢过来一摞门店表让把上面的中文地址全部转成经纬度好画到地图上。这活儿听起来简单真做起来会在地址解析、坐标偏移、频率限制这些地方卡壳。我这次直接用了高德地图的Web服务API拿Python做了地址与经纬度的双向互转——输入一个门牌地址返回坐标输入一个坐标返回可读地址。这篇文章就把这套实例代码拆开讲申请Key、两个方向的调用、返回结果怎么解析、批量情况下怎么限速和重试全是我实际跑过的路子。如果你手头也有一堆地址要做地理可视化或者要给App加一个“当前位置逆解析成文字地址”的功能又或者只是想在脚本里快速查点坐标照着往下走都能跑通。没用过高德开放平台的读者也不用慌申请Key的步骤我会放在代码之前跟着点几下就行。1. 地址转坐标到底解决什么问题先分清两个调用方向1.1 地理编码和逆地理编码就像是“查门牌”和“看附近”地址和经纬度互转表面看是“格式转换”其实是两个不同的服务。正向地理编码也就是地址转坐标。你给它“某市某某区某某街道108号”它返回一个类似“116.481488,39.990464”的坐标点。反过来逆地理编码是坐标转地址。你给它一个坐标它告诉你“这个点大约在某某街道、靠近某某商场”。你可以这样理解正向是查门牌后在地图上定位逆向是你站在地图上某个点抬头看周围是哪儿。这两个方向在我实际接触的项目里基本都会遇到。曾有一个做连锁零售的朋友手里的门店通讯录地址倒是清清楚楚但老板想看这些店在商圈里的分布密度这就必须先把地址批量转成坐标。反过来他给配送员App做定位回传时GPS拿到的是坐标但客户那边只想看“订单员现在在某某路附近”这就得用逆地理编码把坐标翻译成文字。1.2 两个方向各自最典型的应用场景正向地理编码最常见的用途大致有四类地图打点把数据库里的门店、网点、客户地址转换成坐标后叠加到地图图层上一眼看出区域覆盖情况。地址清洗判断两条地址记录是否指向同一个地方与其比对字符串不如先转成坐标再算距离误差小得多。距离估算算两个地址之间的直线距离或配送范围坐标比地址字符串容易算得多。数据可视化按城市、商圈聚合坐标点做热力图、聚类图。逆地理编码的典型场景也对得上设备轨迹回放车载设备上报的是一串坐标回放轨迹时需要知道每个点大致在哪条路上。位置分享给别人发定位时直接把坐标转成“某某路某某号附近”比甩一串数字友好得多。异常点检查数据采集时发现坐标突然跳到奇怪的位置用逆地理编码看看对应地址能快速判断是不是设备漂移。1.3 为什么我选了高德地图的Web服务API国内主流地图服务商都有开放平台但我个人在实际使用中更偏向高德。原因很直接第一地址覆盖面常年够用无论是一线城市还是县城乡镇正向解析的成功率都稳定不至于出现大量“查无此地址”第二它提供了独立的Web服务API直接在服务端用Python请求就能拿结果不依赖任何前端SDK写脚本非常干净第三个人开发者就能申请Key日常项目和小批量任务完全够用不用拉公司营业执照走商务流程。这里需要注意一个点不要因为别人说某家地图好用就盲选还是要先拿自己的真实数据做一百条小样本测试。每家服务商对地址的标准化程度不一样同一个“某某路108号”有的返回精确门牌有的只回落到“某某街道某小区”。我之前的习惯是把两家的结果都跑一遍对比返回的坐标是否集中在合理范围再决定正式用哪家。2. 动手写代码之前Key申请、接口路径和最容易忽略的限制2.1 申请API Key时容易卡住的三个地方申请流程本身不复杂去高德开放平台注册账号进入控制台创建一个应用在应用里添加“Web服务”分类的Key。但有一批人会在这里卡住常见的有三种情况。第一Key类型选错了。如果你要的是服务端脚本调用必须选择“Web服务”不是“Web端(JS API)”也不是“Android/iOS”。选错之后你在脚本里请求会直接提示“10001KEY无效”。第二IP白名单。高德的Web服务Key可以绑定IP白名单。开发阶段我建议先把白名单设置成你的公网出口IP或者干脆留空表示不限制不然换个网络环境调用就会报权限错误。等真正部署到服务器再改成服务器固定IP。第三个人认证。早年有些接口强制要求企业认证现在个人开发者认证后也能使用大部分Web服务接口。具体额度还是以控制台展示为准我只是建议不要一上来就买套餐先用个人额度跑通流程。2.2 两个接口的基本信息和参数对照高德的Web服务API目前有两个地理编码接口路径风格很像正向地理编码/v3/geocode/geo逆地理编码/v3/geocode/regeo下面是我实际常用的参数表基本上一个请求只需要填必填项其余参数按需加。接口方向参数名必填说明正向address是结构化地址例如“某市某某区某某街道108号”正向city否指定城市或区县能提高同名地址的命中率正向output否我固定用json方便Python解析正向batch否是否批量请求一次最多50个地址默认false逆向location是经纬度格式是“经度,纬度”先经度再纬度逆向radius否搜索半径单位米默认1000逆向poitype否指定返回的POI类型比如“商务写字楼”逆向extensions否用all可以取到POI、道路等更多信息2.3 返回码、配额和QPS这三样不看会白跑一天刚开始用的人往往忽略配额和QPS。高德的Web服务API有每日总配额和每秒请求数的限制虽然具体数值会随账号类型变化但设计批量脚本时你必须把它当成“有上限的公共资源”来对待。我问过不少新手第一次写就直接一个for循环跑几千次结果跑到一半收到“10006请求超QPS限制”然后一脸懵。解决办法后面专门有一章讲核心思路就是加限速、加缓存、加重试。另外一个被忽视的点是返回码。高德错误码从10001到10009都有不同含义排错时不要只盯着“请求失败”这四个字。常见情况是返回码含义排查方向10001Key无效或过期检查Key类型、IP白名单、账号状态10003参数错误检查参数名、参数格式尤其注意经纬度分隔符10006请求超出QPS限制降低并发加延时10007请求超出配额当天调用次数用尽换企业Key或明天再跑10009签名错误检查是否开启了签名校验3. 正向地理编码核心代码从中文地址拿到经纬度坐标3.1 一条基础请求的长这样我习惯把Key放到环境变量里或者单独放一个配置文件别写死在脚本中不然代码一旦传到公共仓库Key就泄露了。下面是正向编码的完整示例import requests AMAP_KEY 你的高德Web服务Key def geo_encode(address, city): 正向地理编码地址 - 经纬度 :param address: 结构化地址如某市某某区某某街道108号 :param city: 可选限定城市或区县提升同名地址命中率 :return: (经度, 纬度) 元组或 (None, None) url https://restapi.amap.com/v3/geocode/geo params { key: AMAP_KEY, address: address, city: city, output: json } resp requests.get(url, paramsparams, timeout5) data resp.json() if data.get(status) ! 1: print(f接口返回错误: {data.get(info)}) return None, None geocodes data.get(geocodes, []) if not geocodes: print(f未找到地址: {address}) return None, None # 默认取第一个结果 location geocodes[0].get(location, ) if not location: return None, None lng, lat location.split(,) return float(lng), float(lat) if __name__ __main__: lng, lat geo_encode(某市某某区某某街道108号, city某市) print(lng, lat)这里有个细节requests.get的params参数会自动帮你处理URL编码中文地址、顿号、括号都不用操心。如果你非要用requests.get(url ?address address)这种方式务必先对address做一次URL编码否则地址里带个“”就很容易把请求打废。3.2 返回数据里真正有用的字段location、level和formatted_address正向接口返回的JSON我简化一下是这样的{ status: 1, info: OK, geocodes: [ { location: 116.481488,39.990464, level: 门牌号, formatted_address: 某市某某区某某街道108号 } ] }location就是我们最终要的坐标。但是有两个字段容易被忽略实际业务里非常重要。第一个是level它表示这个解析结果精确到了什么层级。常见值有“省”、“市”、“区县”、“乡镇”、“村庄”、“道路”、“门牌号”、“兴趣点”反正越细越好。如果你想拿做配送距离只有精确到“道路”或“门牌号”的坐标才有意义如果返回的是“市”级别两点之间算出来的距离根本没有参考价值。我写的清洗规则一般是优先保留level为“门牌号”或“兴趣点”的结果次选“道路”实在只剩“区县”级别的先在数据上标记为低质量再决定要不要人工补。第二个是formatted_address它是对输入地址标准化之后的结果。用它可以反推验证如果格式化地址和你输入的内容牛头不对马嘴说明高德没理解你的输入返回的坐标大概率也是偏的。这时候别硬用先检查原地址有没有漏写城市或门牌号。3.3 地址太模糊、多结果命中时怎么处理地址解析不像数学题有唯一标准答案。例如仅输入“某某大厦”结果可能同时返回ABC三个城市的多条记录geocodes数组里就有多条数据。我的策略是三步判断返回数量len(geocodes) 1时记录一条“疑似多结果”日志。按level优先选择精确度高的一条。如果地址里本身没有城市信息请求时尽量带city参数比如“city某市”能大幅减少跨城市重名干扰。如果你要跑的数据量大宁可提前多花十分钟把地址里的省市区字段拆出来传给city也不要迷信高德能自动猜出城市。地址里写“某某路108号”这种缺省信息的真实命中率会低很多。3.4 城市限定city字段的实用技巧city字段应该填到哪一级官方文档里写的是“城市名称或区县名称”。我的经验是直接填市级名称比填区县级更好。比如你在某市有很多区地址分散在各个区统一填“某市”就行如果高德返回的结果里混入了相邻城市的同名路再进一步填“某市某区”。还有一个容易被忽略的场景地址里已经带了省市区但city还是填了另一个区结果高德会按city优先解释返回错误坐标。所以我的代码里做了个简单判断如果address里已经包含明确的省市区关键词city参数就置空让高德按完整地址解析。4. 逆地理编码坐标变成可读地址、区划和周边POI4.1 regeo调用示例代码逆地理编码的调用方式和正向几乎一致唯一要注意的是location参数的顺序先经度后纬度。这个顺序很多人会记反导致坐标跑到另一个半球去。import requests AMAP_KEY 你的高德Web服务Key def regeo_encode(lng, lat, radius1000, extensionsbase): 逆地理编码经纬度 - 可读地址 :param lng: 经度 :param lat: 纬度 :param radius: 搜索半径单位米 :param extensions: base或allall可返回POI、道路信息 :return: 解析后的地址字典或None url https://restapi.amap.com/v3/geocode/regeo params { key: AMAP_KEY, location: f{lng},{lat}, radius: radius, extensions: extensions, output: json } resp requests.get(url, paramsparams, timeout5) data resp.json() if data.get(status) ! 1: print(f接口返回错误: {data.get(info)}) return None return data.get(regeocode)这个函数返回的不是简单字符串而是一个嵌套字典包含结构化地址和周边信息。下面讲怎么从中取你真正需要的内容。4.2 解析formatted_address和addressComponent逆接口返回的关键结构长这样{ formatted_address: 某市某某区某某街道某某路108号, addressComponent: { province: 某省, city: 某市, district: 某区, township: 某某街道, streetNumber: { street: 某某路, number: 108号 } } }formatted_address一眼就能看懂通常直接展示给用户就行。但如果你想做数据筛选比如按区县维度统计那么从addressComponent里拆字段是最靠谱的。直接用formatted_address做字符串匹配一旦地址里出现“某某路108号背侧”这种描述切片就容易出错。还有一个字段township它返回的是街道或镇级单位。配送、选址类业务很喜欢按街道做统计这个字段就很有用。有些接口使用者不知道有它非要从formatted_address里翻字符串属于绕了远路。4.3 周边POI能用来做什么extensionsall时返回结果里会多出pois和roads。POI就是兴趣点比如某个商场、学校、加油站。我一般用两种方式一是异常坐标排查。设备传回来的坐标如果落在荒郊野外逆解析出来的POI大概率是空的或者只有一个偏僻地名。脚本里如果检测到半径500米内没有POI就把这条数据标为“疑似漂移点”。二是业务选址辅助。把一批坐标的周边POI类型拉出来看看周围是餐饮多还是写字楼多虽然不如专业选址数据细但做一个初步的商圈画像完全够用。4.4 逆地理解析的精度边界不是你定位不准是接口做不到很多第一次用的读者会拿着手机GPS给的坐标去反查发现返回的地址和自己实际所在位置差了一条街然后以为高德地图逆地理编码不准。其实这是精度边界问题逆地理编码给你的是“离坐标最近的规范化地址”不是“这个精确位置的门牌号”。加上设备GPS本身有误差反查结果落在周边几十米范围内完全正常。所以在做产品时不要把逆解析的地址当成绝对精确的定位展示给用户后面加个“大约在”“附近”的修饰词用户接受度会高很多你也不会因为一两百米的偏差被投诉。5. 真实项目里最容易翻车的三个细节坐标偏移、字段误用和错误码定位5.1 坐标系不是一回事GPS坐标和高德坐标差了几百米这是我见过最普遍、最隐蔽的坑。你从手机GPS裸读出来的坐标或者设备模块上报的坐标是WGS-84坐标系而高德地图API用的是GCJ-02坐标系两者之间在全国范围内普遍存在几十米到几百米的偏移。直接拿GPS坐标去调高德的逆地理编码返回的地址很可能偏到隔壁小区。正确的做法是如果坐标来源是GPS先用高德开放平台提供的坐标转换接口把WGS-84坐标转成GCJ-02再去调逆地理编码。转换时需要注意官方坐标转换主要支持的转换方向是GPS转高德反向转换基本不开放因为涉及地图数据的合规问题。这个限制对于大部分设备定位场景其实够用因为设备上报的基本是原始GPS坐标转换一次再去解析地址就行。我的建议是在代码里不要硬编码判断“我这数据是不是GPS坐标”直接提供一个coordinate_convert函数统一做一次转换成本很低但能避免大量坐标偏移导致的脏数据。5.2 location参数顺序和返回值分割越小的地方越容易出错逆地理编码的location参数是“经度,纬度”而很多设备模块输出的习惯是“纬度,经度”。我前阵子写一个读取GPS模块的脚本模块数据手册里清楚地写着输出格式是“lat,lng”我没细看直接把字符串拼到接口参数里结果连续三四个坐标解析出来的地址都在非洲最后排查了十几分钟才发现是顺序反了。正向接口返回的location字段虽然是“经度,纬度”它内部用逗号分隔但在某些Excel处理场景下这个字段会被自动转成科学计数法或者日期格式。所以如果你要把坐标存进CSV建议强制把经度、纬度分成两列列类型设置成文本。这个建议听起来很基础但确实能救回一批因为excel自动格式化而丢掉精度的数据。5.3 错误码定位不要只盯着info字段接口报错时info字段里的描述确实足够友好比如“KEY无效”之类。但有些错误是间歇性的比如QPS超限它会请求一下好一下坏此时单看某一次返回没有意义。我排查这类问题时会在脚本里打印完整响应并记录时间戳然后按时间排序看规律。如果一段时间内的错误码集中在10006说明是限速不够如果集中在10007说明是你的日配额提前用完了如果集中在10001那就要检查账号权限和Key绑定。千万不要改一行代码就去反复试先确认错误码否则你会陷入“改参数-报错-再改参数-再报错”的循环。错误码这块我还想多说一句不要只看错误码本身还要看它出现在什么时机。大批量跑到第3000条报错了和第1条就报错排查方向完全不同。前者大概率是配额或网络问题后者才是代码或者Key配置问题。工程化脚本里一定要把“当次运行到第几条”的信息记下来。5.4 URL编码的隐形坑虽然requests.get(params...)能自动处理URL编码但你还是可能会踩坑。举例来说地址里有括号比如“某某大厦(东门)”半角括号在不同参数传递方式下可能被解析成特殊字符还有地址里的“#”号不编码会被当成URL锚点。所以建议统一走params传参不要自己去拼URL。如果需要自己构造URL记得用urllib.parse.quote或urlencode。这个坑特别隐蔽因为本地测试时地址通常很短很干净一旦上生产数据脏字符全冒出来报错率就开始飙升。6. 批量转换的工程化思路缓存、限速、重试一个都不能少6.1 不要裸奔跑一个for循环你可能会想单个请求搞定了批量就是把地址循环一遍请求接口而已。理论上没错但直接裸奔会撞上三件事日配额耗尽、QPS超限、网络超时中断导致前功尽弃。我这边的建议是大批量任务永远先跑100条小样本。目的有三个一是看地址解析成功率如果前100条里有大量返回空结果说明你的地址数据本身需要清洗先别浪费配额二是估算单条平均耗时推算全量跑完需要多久三是观察返回坐标是否集中在目标城市范围防止因为省市区字段缺失导致全部偏到外省。6.2 缓存设计同一个地址不要请求两遍我做批量清洗时地址表里经常有大量重复比如同一个门店在不同订单里出现了几十次。如果每次出现都去请求接口既浪费配额又拖慢速度。所以我在脚本里加了一层本地缓存。实现很简单用Python自带的sqlite3就行不需要引入重型数据库import sqlite3 import time def init_cache(db_pathgeo_cache.db): conn sqlite3.connect(db_path) conn.execute( CREATE TABLE IF NOT EXISTS geo_cache ( address TEXT PRIMARY KEY, lng REAL, lat REAL, level TEXT, query_time TEXT ) ) return conn def get_cache(conn, address): row conn.execute( SELECT lng, lat, level FROM geo_cache WHERE address ?, (address,) ).fetchone() return row def set_cache(conn, address, lng, lat, level): conn.execute( INSERT OR REPLACE INTO geo_cache VALUES (?, ?, ?, ?, ?), (address, lng, lat, level, time.strftime(%Y-%m-%d %H:%M:%S)) ) conn.commit()每次调用正向地理编码之前先查缓存命中就直接用不命中再请求接口然后把结果写入缓存。对于几万条数据的任务这个设计能把有效API调用量降到原来的三分之一甚至更低。6.3 限速与失败重试给请求留点体面高德Web服务接口有QPS限制不要天真地以为“我就一条一条请求肯定超不了”。我自己写一个几万条的任务时会在循环里加上延时和重试逻辑。简单的做法import time import random def call_with_retry(func, *args, max_retry3, **kwargs): for attempt in range(max_retry): try: return func(*args, **kwargs) except requests.exceptions.Timeout: time.sleep(1 attempt * 2) except Exception: time.sleep(2) return None注意重试不是无脑重试。如果是HTTP层面超时重试是有效的但如果是业务层面返回10007配额不足你再重试一天也不会成功。所以我在重试前会先判断错误类型只有超时和10006限流才做重试其他错误直接落日志人工处理。主循环里每条请求之间加一个time.sleep(0.1)也就是每秒最多10次请求这个频率对大多数人已经足够稳了。如果你的任务量特别大先了解当前Key的QPS上限再决定延时设多少。6.4 结果落库与后续分析坐标存成两列更可靠批量跑完的最终结果我一般用CSV或SQLite落库。CSV适合给业务人员看SQLite适合后续继续分析。落库时记住几个原则经度、纬度拆成两列不要留逗号拼接的字符串。保留level字段方便后续过滤低质量结果。保留原始输入地址和格式化地址两者并存方便排查“为什么这条结果偏了”。记录查询时间以后数据有更新可以按时间判断缓存是否过期。落库之后再做可视化就顺了。把CSV导入地图工具按区县聚合一下门店密度、覆盖盲区一眼就能看出来。喜欢自己动手的也可以结合地理计算库把门店坐标和商圈中心坐标做距离计算输出一张按距离排序的周边竞争分析表。6.5 我现在的标准操作流程这套流程跑过几轮之后我现在处理任何地址和坐标互转的任务都固定按下面这个顺序来先拿100条样本跑一遍看整体成功率和坐标范围确认数据没问题。然后写缓存表把限速和重试逻辑也一并写好最后才全量循环。每次跑完看一眼错误日志把失败的那批地址单独存成一个文件抽空人工核查。几乎没再出过“跑到一半发现配额用光、只能从头再来”的情况。这样做还有一个额外好处任务中途断网了、断电了重启脚本之后已经缓存的地址不会再消耗配额直接接着没跑完的部分继续跑。这个体验真的很重要尤其是处理几万条数据的时候心里踏实得多。再分享一下我踩过几次坑之后的总结如果你要去批量转换地址和坐标最该优先投资的部分不是“用什么地图API”而是“脚本怎么管住自己的请求节奏”。缓存、限速、重试这三件事写好了无论Key的配额多紧张任务都能收尾这三件事不做就算给你一个配额很充裕的Key网络一抖你照样得从头再来。
星期一的活最难干。刚打开电脑业务那边就丢过来一摞门店表让把上面的中文地址全部转成经纬度好画到地图上。这活儿听起来简单真做起来会在地址解析、坐标偏移、频率限制这些地方卡壳。我这次直接用了高德地图的Web服务API拿Python做了地址与经纬度的双向互转——输入一个门牌地址返回坐标输入一个坐标返回可读地址。这篇文章就把这套实例代码拆开讲申请Key、两个方向的调用、返回结果怎么解析、批量情况下怎么限速和重试全是我实际跑过的路子。如果你手头也有一堆地址要做地理可视化或者要给App加一个“当前位置逆解析成文字地址”的功能又或者只是想在脚本里快速查点坐标照着往下走都能跑通。没用过高德开放平台的读者也不用慌申请Key的步骤我会放在代码之前跟着点几下就行。1. 地址转坐标到底解决什么问题先分清两个调用方向1.1 地理编码和逆地理编码就像是“查门牌”和“看附近”地址和经纬度互转表面看是“格式转换”其实是两个不同的服务。正向地理编码也就是地址转坐标。你给它“某市某某区某某街道108号”它返回一个类似“116.481488,39.990464”的坐标点。反过来逆地理编码是坐标转地址。你给它一个坐标它告诉你“这个点大约在某某街道、靠近某某商场”。你可以这样理解正向是查门牌后在地图上定位逆向是你站在地图上某个点抬头看周围是哪儿。这两个方向在我实际接触的项目里基本都会遇到。曾有一个做连锁零售的朋友手里的门店通讯录地址倒是清清楚楚但老板想看这些店在商圈里的分布密度这就必须先把地址批量转成坐标。反过来他给配送员App做定位回传时GPS拿到的是坐标但客户那边只想看“订单员现在在某某路附近”这就得用逆地理编码把坐标翻译成文字。1.2 两个方向各自最典型的应用场景正向地理编码最常见的用途大致有四类地图打点把数据库里的门店、网点、客户地址转换成坐标后叠加到地图图层上一眼看出区域覆盖情况。地址清洗判断两条地址记录是否指向同一个地方与其比对字符串不如先转成坐标再算距离误差小得多。距离估算算两个地址之间的直线距离或配送范围坐标比地址字符串容易算得多。数据可视化按城市、商圈聚合坐标点做热力图、聚类图。逆地理编码的典型场景也对得上设备轨迹回放车载设备上报的是一串坐标回放轨迹时需要知道每个点大致在哪条路上。位置分享给别人发定位时直接把坐标转成“某某路某某号附近”比甩一串数字友好得多。异常点检查数据采集时发现坐标突然跳到奇怪的位置用逆地理编码看看对应地址能快速判断是不是设备漂移。1.3 为什么我选了高德地图的Web服务API国内主流地图服务商都有开放平台但我个人在实际使用中更偏向高德。原因很直接第一地址覆盖面常年够用无论是一线城市还是县城乡镇正向解析的成功率都稳定不至于出现大量“查无此地址”第二它提供了独立的Web服务API直接在服务端用Python请求就能拿结果不依赖任何前端SDK写脚本非常干净第三个人开发者就能申请Key日常项目和小批量任务完全够用不用拉公司营业执照走商务流程。这里需要注意一个点不要因为别人说某家地图好用就盲选还是要先拿自己的真实数据做一百条小样本测试。每家服务商对地址的标准化程度不一样同一个“某某路108号”有的返回精确门牌有的只回落到“某某街道某小区”。我之前的习惯是把两家的结果都跑一遍对比返回的坐标是否集中在合理范围再决定正式用哪家。2. 动手写代码之前Key申请、接口路径和最容易忽略的限制2.1 申请API Key时容易卡住的三个地方申请流程本身不复杂去高德开放平台注册账号进入控制台创建一个应用在应用里添加“Web服务”分类的Key。但有一批人会在这里卡住常见的有三种情况。第一Key类型选错了。如果你要的是服务端脚本调用必须选择“Web服务”不是“Web端(JS API)”也不是“Android/iOS”。选错之后你在脚本里请求会直接提示“10001KEY无效”。第二IP白名单。高德的Web服务Key可以绑定IP白名单。开发阶段我建议先把白名单设置成你的公网出口IP或者干脆留空表示不限制不然换个网络环境调用就会报权限错误。等真正部署到服务器再改成服务器固定IP。第三个人认证。早年有些接口强制要求企业认证现在个人开发者认证后也能使用大部分Web服务接口。具体额度还是以控制台展示为准我只是建议不要一上来就买套餐先用个人额度跑通流程。2.2 两个接口的基本信息和参数对照高德的Web服务API目前有两个地理编码接口路径风格很像正向地理编码/v3/geocode/geo逆地理编码/v3/geocode/regeo下面是我实际常用的参数表基本上一个请求只需要填必填项其余参数按需加。接口方向参数名必填说明正向address是结构化地址例如“某市某某区某某街道108号”正向city否指定城市或区县能提高同名地址的命中率正向output否我固定用json方便Python解析正向batch否是否批量请求一次最多50个地址默认false逆向location是经纬度格式是“经度,纬度”先经度再纬度逆向radius否搜索半径单位米默认1000逆向poitype否指定返回的POI类型比如“商务写字楼”逆向extensions否用all可以取到POI、道路等更多信息2.3 返回码、配额和QPS这三样不看会白跑一天刚开始用的人往往忽略配额和QPS。高德的Web服务API有每日总配额和每秒请求数的限制虽然具体数值会随账号类型变化但设计批量脚本时你必须把它当成“有上限的公共资源”来对待。我问过不少新手第一次写就直接一个for循环跑几千次结果跑到一半收到“10006请求超QPS限制”然后一脸懵。解决办法后面专门有一章讲核心思路就是加限速、加缓存、加重试。另外一个被忽视的点是返回码。高德错误码从10001到10009都有不同含义排错时不要只盯着“请求失败”这四个字。常见情况是返回码含义排查方向10001Key无效或过期检查Key类型、IP白名单、账号状态10003参数错误检查参数名、参数格式尤其注意经纬度分隔符10006请求超出QPS限制降低并发加延时10007请求超出配额当天调用次数用尽换企业Key或明天再跑10009签名错误检查是否开启了签名校验3. 正向地理编码核心代码从中文地址拿到经纬度坐标3.1 一条基础请求的长这样我习惯把Key放到环境变量里或者单独放一个配置文件别写死在脚本中不然代码一旦传到公共仓库Key就泄露了。下面是正向编码的完整示例import requests AMAP_KEY 你的高德Web服务Key def geo_encode(address, city): 正向地理编码地址 - 经纬度 :param address: 结构化地址如某市某某区某某街道108号 :param city: 可选限定城市或区县提升同名地址命中率 :return: (经度, 纬度) 元组或 (None, None) url https://restapi.amap.com/v3/geocode/geo params { key: AMAP_KEY, address: address, city: city, output: json } resp requests.get(url, paramsparams, timeout5) data resp.json() if data.get(status) ! 1: print(f接口返回错误: {data.get(info)}) return None, None geocodes data.get(geocodes, []) if not geocodes: print(f未找到地址: {address}) return None, None # 默认取第一个结果 location geocodes[0].get(location, ) if not location: return None, None lng, lat location.split(,) return float(lng), float(lat) if __name__ __main__: lng, lat geo_encode(某市某某区某某街道108号, city某市) print(lng, lat)这里有个细节requests.get的params参数会自动帮你处理URL编码中文地址、顿号、括号都不用操心。如果你非要用requests.get(url ?address address)这种方式务必先对address做一次URL编码否则地址里带个“”就很容易把请求打废。3.2 返回数据里真正有用的字段location、level和formatted_address正向接口返回的JSON我简化一下是这样的{ status: 1, info: OK, geocodes: [ { location: 116.481488,39.990464, level: 门牌号, formatted_address: 某市某某区某某街道108号 } ] }location就是我们最终要的坐标。但是有两个字段容易被忽略实际业务里非常重要。第一个是level它表示这个解析结果精确到了什么层级。常见值有“省”、“市”、“区县”、“乡镇”、“村庄”、“道路”、“门牌号”、“兴趣点”反正越细越好。如果你想拿做配送距离只有精确到“道路”或“门牌号”的坐标才有意义如果返回的是“市”级别两点之间算出来的距离根本没有参考价值。我写的清洗规则一般是优先保留level为“门牌号”或“兴趣点”的结果次选“道路”实在只剩“区县”级别的先在数据上标记为低质量再决定要不要人工补。第二个是formatted_address它是对输入地址标准化之后的结果。用它可以反推验证如果格式化地址和你输入的内容牛头不对马嘴说明高德没理解你的输入返回的坐标大概率也是偏的。这时候别硬用先检查原地址有没有漏写城市或门牌号。3.3 地址太模糊、多结果命中时怎么处理地址解析不像数学题有唯一标准答案。例如仅输入“某某大厦”结果可能同时返回ABC三个城市的多条记录geocodes数组里就有多条数据。我的策略是三步判断返回数量len(geocodes) 1时记录一条“疑似多结果”日志。按level优先选择精确度高的一条。如果地址里本身没有城市信息请求时尽量带city参数比如“city某市”能大幅减少跨城市重名干扰。如果你要跑的数据量大宁可提前多花十分钟把地址里的省市区字段拆出来传给city也不要迷信高德能自动猜出城市。地址里写“某某路108号”这种缺省信息的真实命中率会低很多。3.4 城市限定city字段的实用技巧city字段应该填到哪一级官方文档里写的是“城市名称或区县名称”。我的经验是直接填市级名称比填区县级更好。比如你在某市有很多区地址分散在各个区统一填“某市”就行如果高德返回的结果里混入了相邻城市的同名路再进一步填“某市某区”。还有一个容易被忽略的场景地址里已经带了省市区但city还是填了另一个区结果高德会按city优先解释返回错误坐标。所以我的代码里做了个简单判断如果address里已经包含明确的省市区关键词city参数就置空让高德按完整地址解析。4. 逆地理编码坐标变成可读地址、区划和周边POI4.1 regeo调用示例代码逆地理编码的调用方式和正向几乎一致唯一要注意的是location参数的顺序先经度后纬度。这个顺序很多人会记反导致坐标跑到另一个半球去。import requests AMAP_KEY 你的高德Web服务Key def regeo_encode(lng, lat, radius1000, extensionsbase): 逆地理编码经纬度 - 可读地址 :param lng: 经度 :param lat: 纬度 :param radius: 搜索半径单位米 :param extensions: base或allall可返回POI、道路信息 :return: 解析后的地址字典或None url https://restapi.amap.com/v3/geocode/regeo params { key: AMAP_KEY, location: f{lng},{lat}, radius: radius, extensions: extensions, output: json } resp requests.get(url, paramsparams, timeout5) data resp.json() if data.get(status) ! 1: print(f接口返回错误: {data.get(info)}) return None return data.get(regeocode)这个函数返回的不是简单字符串而是一个嵌套字典包含结构化地址和周边信息。下面讲怎么从中取你真正需要的内容。4.2 解析formatted_address和addressComponent逆接口返回的关键结构长这样{ formatted_address: 某市某某区某某街道某某路108号, addressComponent: { province: 某省, city: 某市, district: 某区, township: 某某街道, streetNumber: { street: 某某路, number: 108号 } } }formatted_address一眼就能看懂通常直接展示给用户就行。但如果你想做数据筛选比如按区县维度统计那么从addressComponent里拆字段是最靠谱的。直接用formatted_address做字符串匹配一旦地址里出现“某某路108号背侧”这种描述切片就容易出错。还有一个字段township它返回的是街道或镇级单位。配送、选址类业务很喜欢按街道做统计这个字段就很有用。有些接口使用者不知道有它非要从formatted_address里翻字符串属于绕了远路。4.3 周边POI能用来做什么extensionsall时返回结果里会多出pois和roads。POI就是兴趣点比如某个商场、学校、加油站。我一般用两种方式一是异常坐标排查。设备传回来的坐标如果落在荒郊野外逆解析出来的POI大概率是空的或者只有一个偏僻地名。脚本里如果检测到半径500米内没有POI就把这条数据标为“疑似漂移点”。二是业务选址辅助。把一批坐标的周边POI类型拉出来看看周围是餐饮多还是写字楼多虽然不如专业选址数据细但做一个初步的商圈画像完全够用。4.4 逆地理解析的精度边界不是你定位不准是接口做不到很多第一次用的读者会拿着手机GPS给的坐标去反查发现返回的地址和自己实际所在位置差了一条街然后以为高德地图逆地理编码不准。其实这是精度边界问题逆地理编码给你的是“离坐标最近的规范化地址”不是“这个精确位置的门牌号”。加上设备GPS本身有误差反查结果落在周边几十米范围内完全正常。所以在做产品时不要把逆解析的地址当成绝对精确的定位展示给用户后面加个“大约在”“附近”的修饰词用户接受度会高很多你也不会因为一两百米的偏差被投诉。5. 真实项目里最容易翻车的三个细节坐标偏移、字段误用和错误码定位5.1 坐标系不是一回事GPS坐标和高德坐标差了几百米这是我见过最普遍、最隐蔽的坑。你从手机GPS裸读出来的坐标或者设备模块上报的坐标是WGS-84坐标系而高德地图API用的是GCJ-02坐标系两者之间在全国范围内普遍存在几十米到几百米的偏移。直接拿GPS坐标去调高德的逆地理编码返回的地址很可能偏到隔壁小区。正确的做法是如果坐标来源是GPS先用高德开放平台提供的坐标转换接口把WGS-84坐标转成GCJ-02再去调逆地理编码。转换时需要注意官方坐标转换主要支持的转换方向是GPS转高德反向转换基本不开放因为涉及地图数据的合规问题。这个限制对于大部分设备定位场景其实够用因为设备上报的基本是原始GPS坐标转换一次再去解析地址就行。我的建议是在代码里不要硬编码判断“我这数据是不是GPS坐标”直接提供一个coordinate_convert函数统一做一次转换成本很低但能避免大量坐标偏移导致的脏数据。5.2 location参数顺序和返回值分割越小的地方越容易出错逆地理编码的location参数是“经度,纬度”而很多设备模块输出的习惯是“纬度,经度”。我前阵子写一个读取GPS模块的脚本模块数据手册里清楚地写着输出格式是“lat,lng”我没细看直接把字符串拼到接口参数里结果连续三四个坐标解析出来的地址都在非洲最后排查了十几分钟才发现是顺序反了。正向接口返回的location字段虽然是“经度,纬度”它内部用逗号分隔但在某些Excel处理场景下这个字段会被自动转成科学计数法或者日期格式。所以如果你要把坐标存进CSV建议强制把经度、纬度分成两列列类型设置成文本。这个建议听起来很基础但确实能救回一批因为excel自动格式化而丢掉精度的数据。5.3 错误码定位不要只盯着info字段接口报错时info字段里的描述确实足够友好比如“KEY无效”之类。但有些错误是间歇性的比如QPS超限它会请求一下好一下坏此时单看某一次返回没有意义。我排查这类问题时会在脚本里打印完整响应并记录时间戳然后按时间排序看规律。如果一段时间内的错误码集中在10006说明是限速不够如果集中在10007说明是你的日配额提前用完了如果集中在10001那就要检查账号权限和Key绑定。千万不要改一行代码就去反复试先确认错误码否则你会陷入“改参数-报错-再改参数-再报错”的循环。错误码这块我还想多说一句不要只看错误码本身还要看它出现在什么时机。大批量跑到第3000条报错了和第1条就报错排查方向完全不同。前者大概率是配额或网络问题后者才是代码或者Key配置问题。工程化脚本里一定要把“当次运行到第几条”的信息记下来。5.4 URL编码的隐形坑虽然requests.get(params...)能自动处理URL编码但你还是可能会踩坑。举例来说地址里有括号比如“某某大厦(东门)”半角括号在不同参数传递方式下可能被解析成特殊字符还有地址里的“#”号不编码会被当成URL锚点。所以建议统一走params传参不要自己去拼URL。如果需要自己构造URL记得用urllib.parse.quote或urlencode。这个坑特别隐蔽因为本地测试时地址通常很短很干净一旦上生产数据脏字符全冒出来报错率就开始飙升。6. 批量转换的工程化思路缓存、限速、重试一个都不能少6.1 不要裸奔跑一个for循环你可能会想单个请求搞定了批量就是把地址循环一遍请求接口而已。理论上没错但直接裸奔会撞上三件事日配额耗尽、QPS超限、网络超时中断导致前功尽弃。我这边的建议是大批量任务永远先跑100条小样本。目的有三个一是看地址解析成功率如果前100条里有大量返回空结果说明你的地址数据本身需要清洗先别浪费配额二是估算单条平均耗时推算全量跑完需要多久三是观察返回坐标是否集中在目标城市范围防止因为省市区字段缺失导致全部偏到外省。6.2 缓存设计同一个地址不要请求两遍我做批量清洗时地址表里经常有大量重复比如同一个门店在不同订单里出现了几十次。如果每次出现都去请求接口既浪费配额又拖慢速度。所以我在脚本里加了一层本地缓存。实现很简单用Python自带的sqlite3就行不需要引入重型数据库import sqlite3 import time def init_cache(db_pathgeo_cache.db): conn sqlite3.connect(db_path) conn.execute( CREATE TABLE IF NOT EXISTS geo_cache ( address TEXT PRIMARY KEY, lng REAL, lat REAL, level TEXT, query_time TEXT ) ) return conn def get_cache(conn, address): row conn.execute( SELECT lng, lat, level FROM geo_cache WHERE address ?, (address,) ).fetchone() return row def set_cache(conn, address, lng, lat, level): conn.execute( INSERT OR REPLACE INTO geo_cache VALUES (?, ?, ?, ?, ?), (address, lng, lat, level, time.strftime(%Y-%m-%d %H:%M:%S)) ) conn.commit()每次调用正向地理编码之前先查缓存命中就直接用不命中再请求接口然后把结果写入缓存。对于几万条数据的任务这个设计能把有效API调用量降到原来的三分之一甚至更低。6.3 限速与失败重试给请求留点体面高德Web服务接口有QPS限制不要天真地以为“我就一条一条请求肯定超不了”。我自己写一个几万条的任务时会在循环里加上延时和重试逻辑。简单的做法import time import random def call_with_retry(func, *args, max_retry3, **kwargs): for attempt in range(max_retry): try: return func(*args, **kwargs) except requests.exceptions.Timeout: time.sleep(1 attempt * 2) except Exception: time.sleep(2) return None注意重试不是无脑重试。如果是HTTP层面超时重试是有效的但如果是业务层面返回10007配额不足你再重试一天也不会成功。所以我在重试前会先判断错误类型只有超时和10006限流才做重试其他错误直接落日志人工处理。主循环里每条请求之间加一个time.sleep(0.1)也就是每秒最多10次请求这个频率对大多数人已经足够稳了。如果你的任务量特别大先了解当前Key的QPS上限再决定延时设多少。6.4 结果落库与后续分析坐标存成两列更可靠批量跑完的最终结果我一般用CSV或SQLite落库。CSV适合给业务人员看SQLite适合后续继续分析。落库时记住几个原则经度、纬度拆成两列不要留逗号拼接的字符串。保留level字段方便后续过滤低质量结果。保留原始输入地址和格式化地址两者并存方便排查“为什么这条结果偏了”。记录查询时间以后数据有更新可以按时间判断缓存是否过期。落库之后再做可视化就顺了。把CSV导入地图工具按区县聚合一下门店密度、覆盖盲区一眼就能看出来。喜欢自己动手的也可以结合地理计算库把门店坐标和商圈中心坐标做距离计算输出一张按距离排序的周边竞争分析表。6.5 我现在的标准操作流程这套流程跑过几轮之后我现在处理任何地址和坐标互转的任务都固定按下面这个顺序来先拿100条样本跑一遍看整体成功率和坐标范围确认数据没问题。然后写缓存表把限速和重试逻辑也一并写好最后才全量循环。每次跑完看一眼错误日志把失败的那批地址单独存成一个文件抽空人工核查。几乎没再出过“跑到一半发现配额用光、只能从头再来”的情况。这样做还有一个额外好处任务中途断网了、断电了重启脚本之后已经缓存的地址不会再消耗配额直接接着没跑完的部分继续跑。这个体验真的很重要尤其是处理几万条数据的时候心里踏实得多。再分享一下我踩过几次坑之后的总结如果你要去批量转换地址和坐标最该优先投资的部分不是“用什么地图API”而是“脚本怎么管住自己的请求节奏”。缓存、限速、重试这三件事写好了无论Key的配额多紧张任务都能收尾这三件事不做就算给你一个配额很充裕的Key网络一抖你照样得从头再来。
