简介一份面向前端开发者的天地图API地图开发源码示例包基于Vue与Element Plus构建覆盖地图初始化、标记管理、搜索、测距、卫星/地图切换、全屏显示、天气信息、定位及标记增删等常见功能适合需要快速接入天地图能力的中级前端工程师参考。包体共2000个文件其中1904个JS文件承载业务与第三方库逻辑55个Markdown文档可作说明与笔记41个JSON配置用于项目配置与数据示例整体31.7MB结构清晰便于筛选复用。目前已有99人学习下载。拿到后可直接解压查看完整案例代码对照学习组件化地图应用搭建、API接入与交互细节也能复制天气、定位、测距等模块到自有项目中大幅减少从零排查天地图API的时间成本。1. 天地图API开发示例绕不开的三道坎Token、坐标系、图层类型天地图API开发示例看起来是一份源码实际上是三道坎Token怎么配、坐标系怎么选、图层类型怎么切。地图页面的色块转圈、黑屏、点位偏移几十米这些问题基本都出在这三个点上而不是出在画图的代码上。我见过不少开发者拿到示例后直接把脚本引进去控制台返回401然后就开始怀疑源码包不完整。这类示例源码的价值是把底图加载、地理编码、逆地理编码这些高频诉求拧成最小可运行骨架。你真正要做的不是把文档背下来而是把tk、图层名、投影后缀三个变量接对页面交互部分就是常规Web开发。一个能跑的示例往往不到200行里面大半是在拼瓦片URL和解析接口返回。这篇开发记录适合两类读者。一类是前端开发者手头的业务系统催着在一两天内把地图模块跑出真图另一类是后端开发者想用Python批量把地址转成坐标再落库分析。如果你正好是其中一类按章节往下走就行。2. 拆源码前先补课Token、图层类型、坐标系怎么影响结果2.1 无处不在的tk源码里为什么会有两个Token天地图所有请求都要求在URL里带一个tk参数不管是请求瓦片底图、调地理编码接口还是逆地理编码后端都会先校验这个值。校验不过就是401页面一片空白。源码里一般会有一个独立的配置文件来统一存放它而不是散落在各个请求里。我习惯把配置单独放在config.js里并且把浏览器端和服务端的密钥分开。前端页面用的key会校验域名白名单服务端程序用的key适合在后端脚本里调用两者混用是后面要踩的大坑。// config.js —— 源码里所有请求共用的Token配置 const TDTSDK_CONFIG { // 浏览器端密钥用于前端瓦片请求、页面内API调用 tk: 请替换成浏览器端密钥, // 服务端密钥用于Python/Java等后端服务不放到前端代码里 serverTk: 请替换成服务端密钥, // 默认底图图层vec 矢量底图、img 影像、ter 地形 defaultLayer: vec, // 投影后缀c 表示球面墨卡托w 表示经纬度 projection: c };这里把tk单独抽出来是为了将来从开发环境切到生产环境时只改这一个文件。注意serverTk不要写进会被浏览器加载的JS里服务端密钥一旦暴露别人能拿着它高强度调用你的账户配额。config.js里只放前端tk服务端tk放到后端环境变量里这是我固定下来的项目习惯。2.2 图层类型对照矢量、影像、地形标注怎么切换天地图的数据按内容分成几大类瓦片URL里的LAYER参数决定取哪一类。矢量底图是vec矢量中文注记是cva影像底图是img影像中文注记是cia地形晕渲是ter地形注记是cta。底层逻辑是一张底图配一张对应注记层底图出图注记出地名和道路名称。图层效果LAYER参数缩放级别建议典型用途矢量底图vec3-18街道图、做业务叠加矢量中文注记cva5-18盖在vec上方显示地名影像底图img3-18卫星图浏览影像中文注记cia5-18盖在img上方显示地名地形晕渲ter3-18地形地貌展示地形中文注记cta5-18配合ter使用注意注记层不能单独当底图用它是透明图层底下必须有对应底图。我把源码里切换图层的逻辑封装成一个函数核心是移除旧瓦片图层再添加新图层不然每次切换地图上会积累一大堆看不见的请求。// 通用底图替换函数newLayer 传 vec、img 或 terprojection 传 c 或 w function replaceLayer(map, newLayer, projection) { // 保存当前瓦片对象到map实例上方便下次切换时移除 if (map._tileLayer) { map.removeLayer(map._tileLayer); } var url https://t{s}.tianditu.gov.cn/ newLayer _ projection /wmts? SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYER newLayer STYLEdefaultTILEMATRIXSET projection FORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk TDTSDK_CONFIG.tk; map._tileLayer L.tileLayer(url, { subdomains: [0, 1, 2, 3, 4, 5, 6, 7], maxZoom: 18 }).addTo(map); }这段代码我把URL模板全部收敛在一个函数里源码里其他任何地方都不直接拼瓦片地址。这样换图层时只要传一个名字不用关心这层是瓦片还是注记。参数说明newLayer决定数据内容projection决定坐标切片方式subdomains让Leaflet把请求轮询到8个子域上避免集中在同一个域名导致浏览器并发限制。2.3 坐标系选错的结果从图片错位到HTTP 404天地图同一个图层提供了两种投影后缀URL里的TILEMATRIXSET参数用c表示球面墨卡托用w表示CGCS2000经纬度切片。Leaflet默认的坐标系是EPSG:3857跟c后缀的墨卡托切片是对应的所以前端直接加载vec_c这类地址最省事。如果你拿着w后缀的地址喂给Leaflet图片能拼出来但会明显错位因为切片网格的口径对不上。反过来说后端做坐标计算、按经纬度查瓦片行列号时w后缀的经纬度切片更容易推理。很多源码示例用的是w到了浏览器里就翻车就是这个原因。我通常在源码的配置里固定一个projection字段所有瓦片URL都由它生成比在几十处代码里手工改后缀可靠得多。使用场景推荐投影后缀坐标系基底Leaflet/OpenLayers前端加载cWeb墨卡托官方JS API加载wCGCS2000经纬度Python批量计算瓦片坐标按需用c或w与目标一致需要与其他CGCS2000数据叠加wCGCS2000经纬度选错坐标系时最典型的现象是瓦片请求返回200地图能显示但Marker位置和底图上的真实地物差开几条街往东南或西北方向漂移。还有更隐蔽的情况影像图和矢量图叠加不重合一层对上了另一层必然偏。后面第5章会专门讲怎么排查这类偏移。3. 最小可运行源码从HTML到第一张矢量底图3.1 源码包里五个关键文件与请求链路示例源码不管具体怎么组织核心文件基本是这五类。index.html是页面入口挂地图容器config.js放Token和图层配置lib/leaflet/放本地依赖的Leaflet库js/layer.js封装底图加载和图层切换js/geocoder.js封装地理编码调用。把Leaflet放在本地而不是引公网CDN主要是为了内网部署和版本固定万一离线环境页面也能正常加载。文件/目录作用拿到源码后要动吗index.html页面入口包含地图div和初始化脚本基本不动config.jstk、图层名、投影后缀必须改lib/leaflet/Leaflet本地依赖不动js/layer.js加载底图、替换图层、加Marker按需改js/geocoder.js正逆地理编码接口封装按业务改页面跑起来的请求链路很简单index.html加载完Leaflet和config.jslayer.js读取config里的tk和图层参数拼出天地图瓦片URLLeaflet根据地图中心点和缩放级别按需请求当前视野内的瓦片并拼成整图。看到地图渲染出来链路就通了。3.2 加载矢量底图的最小HTML下面这段是可以直接保存成index.html运行的最小源码。它只做一件事以指定经纬度为中心加载一张矢量底图。这段代码假设你已经把Leaflet的文件放在了lib/leaflet/下面。!DOCTYPE html html langzh-CN head meta charsetutf-8 title天地图API开发示例 - 最小矢量底图/title link relstylesheet hreflib/leaflet/leaflet.css script srclib/leaflet/leaflet.js/script script srcconfig.js/script /head body div idmap styleheight:100vh;width:100vw/div script // 初始化地图第二个参数是缩放级别 var map L.map(map).setView([35.5, 105.0], 5); // 加载天地图矢量底图投影后缀用c与Leaflet默认投影一致 L.tileLayer( https://t{s}.tianditu.gov.cn/vec_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk TDTSDK_CONFIG.tk, { subdomains: [0, 1, 2, 3, 4, 5, 6, 7], maxZoom: 18 } ).addTo(map); /script /body /html初始化时setView传的是经纬度第一个参数是纬度第二个是经度这个顺序经常有人反过来写一旦反了地图中心就跑到奇怪的地方。瓦片URL里TILEMATRIX是缩放级别TILEROW和TILECOL是行列号Leaflet会自动用当前视野算出这些值替换到模板里。如果页面一片空白按F12看Network面板找到瓦片请求的返回状态。401就是tk有问题200但大片灰色可能是投影后缀不对404通常是URL模板里某个参数拼错了。这一条排查顺序能解决九成的地图白屏问题。3.3 换影像、注记和地形改三个参数即可把矢量底图换成影像只需要把LAYER和URL里的vec改成img同时把TILEMATRIXSET保持c。影像图只有卫星照片没有地名所以实际项目里通常还要叠一层影像中文注记cia让地名和道路名称出现在图上。叠加顺序是影像底图在下注记层在上这样地名才看得清楚。// 先加载影像底图 replaceLayer(map, img, c); // 再加载影像中文注记层annotation变量保存后续可移除的图层 var annotation L.tileLayer( https://t{s}.tianditu.gov.cn/cia_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERciaSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk TDTSDK_CONFIG.tk, { subdomains: [0, 1, 2, 3, 4, 5, 6, 7], maxZoom: 18 } ).addTo(map); // 注记层放在底图上方避免被后续业务图层遮住 annotation.setZIndex(5);提示注记层是透明图单独加载看不到任何地图内容必须和对应底图同时使用。矢量、影像、地形三套注记参数是cva、cia、cta不要混用拿cia去盖矢量底图会看到一堆地名对不上道路。影像图和注记层的缩放级别可以不同。实际做图时我习惯在缩放级别小于10时只显示影像放大到11以上再让注记出现这样小比例尺下地图不糊。具体阈值要看业务但至少应该在源码里留一个根据zoom控制图层显隐的钩子不要把所有图层无脑叠加到所有级别。3.4 把业务点位标到图上Marker、Popup与坐标顺序底图通了之后第二步通常是往图上放业务点位。Marker的坐标同样用经纬度数组纬度在前经度在后。代码里加一个点位和Popup放到地图上即可。// 给地图加一个业务点位坐标用[纬度, 经度] var marker L.marker([35.5, 105.0]).addTo(map); marker.bindPopup(纬度 35.5br经度 105.0).openPopup();如果这个点是后端接口返回的要注意后端给的字段顺序。有的接口返回lon在前、lat在后落进Marker数组时没转过来点位就会显示在另一个位置。我会在封装Marker的地方统一做一次转换后端只管传JSON前端负责把lon/lat转成[lat, lon]这样不管接口怎么变页面上的坐标顺序永远是统一的。如果点位和底图之间只差了几十米不是顺序问题而是坐标系问题。CGCS2000和WGS-84在大部分区域差异很小但叠加要求高时就得做转换。这个在后文第6章的进阶工具里会给一个可复用的解法。4. 服务端调用天地图服务API正地理编码与逆地理编码的源码写法4.1 地理编码接口的URL结构与三个关键参数天地图的服务API里地理编码接口通过HTTP的GET请求完成参数直接放在URL里。正向地理编码传地址文本得到经纬度逆地理编码传经纬度得到地址描述。两者共用同一个接口地址靠参数区分调用方向。正向请求的核心参数是ds里面是一个JSON字符串包含keyWord和level两个字段。keyWord是地址关键词level是行政区划等级决定匹配粒度。逆请求的核心参数是postStr里面包含lon、lat、ver和type。URL最后统一带tk用服务端密钥。下面是两种请求原始形态的写法。# 正向地理编码地址文本 - 经纬度 https://api.tianditu.gov.cn/geocoder?ds{keyWord:某开发区管委会,level:district}tk服务端密钥 # 逆地理编码经纬度 - 地址描述 https://api.tianditu.gov.cn/geocoder?postStr{lon:105.0,lat:35.5,ver:1.1,type:geocode}typegeocodetk服务端密钥注意URL里出现中文和花括号时浏览器或HTTP客户端会自动做URL编码手写curl时反而容易因为引号不匹配失败。建议用编程语言构造请求让requests或HttpClient来处理编码少碰原生URL拼接。4.2 Python批量正地理编码地址列表转坐标清单服务端最常见的需求是拿一批地址换坐标落库。下面这个函数封装了正向地理编码输入地址和tk返回经纬度。第一次写完建议先打印原始返回JSON确认字段结构再正式用。import requests def geocode_to_latlng(address, tk): # 正向地理编码地址 - 经纬度 # ds参数是JSON字符串keyWord为地址level为匹配等级 params { ds: {keyWord:%s,level:district} % address, tk: tk } resp requests.get( https://api.tianditu.gov.cn/geocoder, paramsparams, timeout5 ) resp.raise_for_status() data resp.json() # 第一次调试时先print(data)确认字段路径再继续 if data.get(status) OK: loc data[result][location] return loc[lon], loc[lat] return None, None这段代码里ds必须是JSON字符串不能直接传Python字典否则requests会把花括号里的内容按查询参数格式拆开接口就解析不到keyWord了。timeout设5秒是防止某个地址让接口超时把整个任务拖死。接口返回的status字段不是HTTP状态码是业务状态HTTP 200不代表查到了地址一定要判断业务status再取值。4.3 逆地理编码经纬度列表转地址描述逆地理编码的入参换成经纬度返回里包含地址描述、兴趣点等字段。实际项目里常用于给业务轨迹点补地址描述或者验证坐标是否落在目标区域内。def reverse_geocode(lon, lat, tk): # 逆地理编码经纬度 - 地址描述 # postStr必须是JSON字符串ver固定传1.1type为geocode post_str {lon:%s,lat:%s,ver:1.1,type:geocode} % (lon, lat) params { postStr: post_str, type: geocode, tk: tk } resp requests.get( https://api.tianditu.gov.cn/geocoder, paramsparams, timeout5 ) resp.raise_for_status() data resp.json() if data.get(status) OK: # result的结构以实际打印为准不同版本返回内容不一样 return data[result] return None这个函数返回整个result对象取出地址字段之后再进一步加工。我建议先把result原样落入日志或数据库等字段稳定了再做结构化解析不要一开始就只取某一个字段否则接口字段一改你的程序就静默返回None。4.4 批量调用的限速策略sleep与重试免费配额下批量调地理编码最容易碰到的问题不是参数错误而是请求太密触发限流。几百条地址连续快速请求跑到一半开始出现超时或异常响应那就是频率撞上限了。import time for addr in address_list: lon, lat geocode_to_latlng(addr, service_tk) if lon is not None: print(addr, lon, lat) # 控制请求频率避免触发QPS限制要更大批量就先分片再跑 time.sleep(0.2)sleep间隔需要根据实际配额调整。我一般先跑50条试节奏观察有没有连续超时没有就把间隔缩短到0.1秒有了就加到0.5秒。比一味加重试更稳妥重试太多只会把限流窗口填满。5. 常见问题与排查Token失效、图层偏移、跨域与限流这么定位5.1 Token 401浏览器端密钥与服务端密钥混用的典型错误现象页面瓦片全部加载失败Network里每个请求都是401服务端调用地理编码也报客户端错误。原因最常见的是前端页面用了服务端密钥。天地图会校验请求来源浏览器端密钥和白名单绑定服务端密钥被前端页面直接使用时会因为来源不匹配被拒。还有一种是本地页面用file://协议打开白名单里的localhost不命中。解决config.js里确认放的是浏览器端密钥。本地开发时用http://localhost加端口访问把对应地址加进密钥白名单。如果项目要部署到别的域名上线前提前把正式域名加白名单这个流程容易在发布日被漏掉建议放到部署检查单里。5.2 点位偏移几十米坐标系混用的血泪经验现象Marker和底图上的真实地物隔开几十米或者影像底图和矢量底图叠加不重合。地图能加载看起来一切正常就是位置差一口气。原因瓦片URL里投影后缀和前端坐标系不匹配。Leaflet默认EPSG:3857加载的是vec_c这种墨卡托切片偏要改成vec_w就会按经纬度网格去请求墨卡托坐标系里的坐标结果自然是整体偏移。后端算出来的坐标是CGCS2000经纬度直接丢给前端点位也会有同样的问题。解决先在源码里统一一处配置投影后缀前端统一用c后端业务数据如果拿到的是w口径的经纬度先转成墨卡托系的坐标再显示。或者反过来给Leaflet定义EPSG:4490的坐标系来加载w切片但那条路线要引入额外的投影库不是必须时我不选。这个坑排查起来很耗时间是因为它不报错只让你看到结果差几十米属于地图开发里典型的玄学问题实际原因就在c和w这两个字母上。5.3 浏览器直接调服务API被跨域拦截三选一现象在页面里用fetch或axios直接请求api.tianditu.gov.cn的geocoder接口控制台报跨域错误服务端用Postman调又是好的。原因浏览器同源策略拦截了跨域响应Postman没有这个限制所以同样的URL在Postman通、在浏览器里不通。解决方案首选服务端代理前端请求自己的后端接口后端再转发到天地图顺带把tk藏在服务端其次是尝试在URL上加callback参数走JSONP但这个方案受接口支持限制且不如代理稳定最次是浏览器插件临时跨域只适合调试不适合线上。实际项目里只要有一次代理转发后面换密钥、加日志都方便很多。5.4 高频请求间歇性超时限流不该用重试硬扛现象批处理跑到第几百条时请求开始随机超时偶尔返回非JSON内容再跑一次又能好一段时间。原因短时间内的请求数量超过了配额限制触发了限流。限流一般不是硬切断而是让你间歇性失败这比直接报错更迷惑人。解决循环里增加sleep控制频率把大任务拆成小批次每批之间停一段时间。观察返回内容里的错误提示确认是频率问题还是参数问题再动手。重试机制只做超时重试和瞬时网络抖动重试不要对限流错误做无脑重试。6. 进阶把坐标转换和图层叠加做成通用工具6.1 用pyproj把CGCS2000坐标转Web墨卡托并计算瓦片行列号有些场景需要知道某个经纬度在指定缩放级别下落在哪张瓦片比如调试瓦片加载范围、按网格统计坐标点。天地图的c后缀切片就是Web墨卡托网格用pyproj转完坐标再算行列号即可。from pyproj import Transformer # 定义CGCS2000经纬度到Web墨卡托的转换器 trans Transformer.from_crs(EPSG:4490, EPSG:3857, always_xyTrue) lon, lat 105.0, 35.5 x, y trans.transform(lon, lat) def tile_xy(x, y, zoom): # Web墨卡托坐标转瓦片行列号zoom为缩放级别 n 2 ** zoom xtile int((x 20037508.342789) * n / 40075016.068578) ytile int((20037508.342789 - y) * n / 40075016.068578) return xtile, ytile这条转换能直接定位坐标对应的瓦片范围排查某一级地图不显示时很好用。公式里的两个常量分别表示Web墨卡托全域范围和半个范围属于固定值不需要改动。如果只想要坐标转换不关心行列号那Transformer两行代码就够了。6.2 把图层叠加封成函数底图、注记、业务图层用zIndex分层多图层叠加时最麻烦的是层级关系乱掉。给每个瓦片图层显式设置zIndex比依赖添加顺序更可靠。我习惯把这一步也封装成公共函数所有图层走同一个入口。// 添加带zIndex的瓦片图层方便控制底图/注记/业务层顺序 function addTileLayer(map, url, zIndex) { var layer L.tileLayer(url, { subdomains: [0, 1, 2, 3, 4, 5, 6, 7], maxZoom: 18 }); layer.setZIndex(zIndex); layer.addTo(map); return layer; }底图设1注记设5业务点位图层设10。这样后期无论怎么调整加载顺序层级都不会乱。同样的原则也适用于Marker和Popup。6.3 两个土办法验证底图是否正确第一个办法是直接在命令行请求一张瓦片看HTTP状态码。用curl带tk拉一张第3层级的小瓦片返回200且内容有长度说明密钥、投影、URL模板这条链路全通。第二个办法是找一个自己确认过位置的地物把Markerr放上去连续缩放几级看偏差是否恒定。恒定偏差就是坐标系问题只在某几级偏就是瓦片层级或缓存问题。curl -I https://t0.tianditu.gov.cn/vec_c/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERvecSTYLEdefaultTILEMATRIXSETcFORMATtilesTILEMATRIX3TILEROW3TILECOL3tk你的tk我自己的习惯是拿到任何示例源码第一件事先把config.js打开改掉tk和projection然后才看页面。早年间接过一个地图模块上来就调样式结果在点位偏移上耗了一整天后来发现只是c和w两个字母的问题。现在无论多急的排期固定配置先做其余功能再逐个往上加。希望帮到你。本文还有配套的精品资源点击获取