天地图2024版正式启用之后我做的第一件事就是把新上线的多时相影像专题从头到尾拖了一遍。历史影像能在网页端直接按时间轴切换不用下载、不用申请项目、不用等切片打包这件事对常年跟遥感数据打交道的人来讲意义比表面上看着要大得多。以前想做一次某地块五年前是什么样的核查要么去翻商业卫星影像的存档订单要么在几个公开的影像服务里碰运气运气不好的时候两个年份的分辨率差一个量级连道路走向都对不上。现在一个入口、一条时间轴把这活儿拉平了不少。这篇东西写给三类人看一类是刚接触天地图、只想看看自家小区十年前什么样的小白一类是GIS专业出身或者正在做项目的从业者关心arcgis加载在线天地图的安装步骤详解、arcgis pro如何连线天地图、gispro显示天地图地形图这些具体操作还有一类是做开发的同学天天琢磨天地图api的使用教程、天地图key调用地图以及怎么收拾那个让人头大的返回code: 301001 / 非法key。下面我按先看懂它是什么—再搞定账号和坐标—再上手网页端—再进桌面GIS—最后做二次开发的顺序往下写中间穿插我自己踩过的坑。1. 多时相影像专题到底解决了什么问题1.1 从一张现状快照到一条时间轴过去的在线底图本质上是一张现状快照。服务方拿到最新一版影像切好瓦片铺上去旧的那一版就下线了。你想看两年前的样子得靠运气——要么是遥感数据商手里还留着存档要么是某个项目单位自己存了一份。这就带来一个很现实的问题做土地核查、工程审计、河道演变、城市扩张分析的时候最难拿到的证据恰恰是当时是什么样而不是现在是什么样。多时相影像专题改的就是这个逻辑。它把不同时期获取的影像按时间顺序组织起来形成一条可以来回拖动的时间轴用户在同一个位置、同一个视角下切换年份看到的还是那块地只是天上的快门时间变了。这个改动听起来简单实现起来其实挺麻烦不同时相的影像在获取角度、太阳高度角、云量、色彩均衡上都不一致直接并排摆着会像两张不同星球的地图。所以专题里能做的是尽量对齐空间参考、统一瓦片层级、拉平色调让你在做对比的时候注意力能集中在真实的物理变化上而不是被色差带偏。1.2 三类最典型的用武之地第一类是变化核查。这是用得最多的场景。比如某块地在2021年的影像上还是农用地在2024年的影像上变成了硬化地面两期影像一放时间、位置、范围全都有据可查。这类工作以前要跑现场、要对图纸现在至少能先在网上做一轮初筛把可疑点位圈出来再决定要不要去实地。第二类是工程与项目的生命周期回溯。修一条路、建一个园区往往跨越好几年中间还有停工、复工、变更。多时相影像能把这条时间线补完整哪一年动工、哪一年主体封顶、哪一年开始绿化一目了然。我见过做工程结算的朋友为了确认某个阶段的施工进度翻箱倒柜找当时的照片现在这类争议很多时候网上就能settle掉一大半。第三类是自然与环境的长期观察。河口的淤积、湖泊的退缩、海岸线的进退、矿区的复垦这些变化在单期影像上根本看不出来必须有时间序列才有意义。特别是2025历史影像这类说法开始在网上流传之后很多做生态监测的团队都在问能不能拿到连续几年的同源影像多时相专题正好填了这个坑。1.3 它和商业影像、历史地图服务的差别在哪我得把话说清楚避免有人拿它当万能钥匙。多时相影像专题给你的是影像不是测绘成果。它的优势是免费、易得、中文界面友好、和国内坐标系天然贴合它的短板也很明显不同期次的影像分辨率可能不一致早期年份的覆盖完整度和云量控制未必理想时间间隔不是均匀的有的区域可能只有两三期有的区域有七八期。你要拿它做厘米级的地籍测量那是用错了工具你要拿它做宏观变化判读、做汇报里的示意图、做项目前期摸底它非常好用。另外一个容易被混淆的概念是历史影像地图。市面上有些产品确实提供历史影像但多数是商业卫星的按需订购或者需要单独授权的存档服务价格和门槛都不低。天地图把这个入口免费开出来对个人研究者和中小团队来说实际价值远大于功能列表上的那几行字。2. 动手之前Key、白名单、坐标系这三关先过2.1 开发者Key的申请与服务端/浏览器端的选择不管你是看网页、接ArcGIS还是自己写代码调天地图api都得先有一个Key也就是常说的tk。申请流程本身不复杂但有几个地方选错了后面会一直报错。大致路径是注册账号、完成实名信息填写、进入开发者控制台、新建一个应用、在应用里勾选你需要的服务类型然后拿到那串Key。这里有三个关键选择我按重要性排一下。第一是Key的类型。控制台通常会区分浏览器端和服务端两种用途。浏览器端的Key会校验来源域名Referer适合放在网页里服务端的Key会校验请求来源IP适合放在后端程序或者桌面端工具里。你要是把服务端Key塞进前端页面大概率会被非法key挡住反过来浏览器端Key在一个没有请求头来源信息的程序里调用也一样过不去。第二是白名单。浏览器端要填域名服务端要填IP段这一步很多人图省事跳过结果测试的时候好好的一上线就挂。第三是服务的勾选。控制台里通常要单独勾选底图、注记、地形等类别没勾的服务即使Key有效也会被拒。提示个人开发者和小团队最好给每个项目单独建一个Key别全项目共用一个。一旦某个Key因为配额或者误用被限制其他项目不会跟着遭殃排查起来也更容易定位。2.2 301001 非法Key从我踩过的坑倒推排查顺序返回code: 301001 / 非法key是搜索量最高的一个问题我把它当成一个标准排查流程来写。这个错误的意思是服务端拒绝了你的凭证但拒绝的原因有十来种从后往前查效率最高。第一步看Key本身。最常见的是复制粘贴时多带了空格或者URL里被转义成了amp;又或者拼接参数时tk写成了key。这种低级错误占了我见过的问题里将近三成。第二步看Key的类型和调用方式是否匹配——在网页里用服务端Key在Python脚本里用浏览器端Key都会撞墙。第三步看白名单。第四步看Key是否还在有效期、服务是否已勾选。第五步看当日配额是不是打满了。现象高概率原因处理方向本地测试正常部署后报301001域名白名单没加部署域名控制台补白名单注意区分http与https网页能显示Python脚本报301001用了浏览器端Key换成服务端Key并配置IP白名单昨天还能用今天突然不行配额用尽或Key被限制看控制台用量必要时换Key或提升配额所有请求都报301001Key拼写错误或参数名写错逐字符比对官方示例URL只有某几个图层报错该项服务未勾选控制台补勾对应服务301001之外301段还有几个兄弟码分别对应无权限、配额超限、白名单不匹配这几类情况。具体哪个码对应哪种原因以控制台和官方文档的说明为准但排查思路是共通的先怀疑自己拼错再怀疑类型选错最后怀疑配额。这个顺序能省掉你80%的时间。2.3 坐标系速查为什么天地图不用纠偏这是必须单独讲清楚的一点因为它能解释你后面遇到的大部分偏移问题。天地图采用的是2000国家大地坐标系CGCS2000而CGCS2000和WGS84在数值上的差异是厘米级的日常使用中可以认为它们基本重合。这意味着你从GPS设备或者手机定位拿到的经纬度直接叠到天地图的影像上正常情况下是对得上的不需要做偏移纠正。但如果你拿的是高德、腾讯这类国内互联网地图的坐标点那是另一套加密后的坐标系直接叠到天地图上会出现几十米到上百米的错位这时候必须先做坐标转换。我在项目里见过太多这种案例同事从某个地图App里抄了一个点位叠到ArcGIS里的天地图影像上发现落在河里然后开始怀疑是影像偏移折腾了半天才发现是坐标系不匹配。另外还要区分两件事投影和坐标系。天地图的WMTS服务带_w后缀的是球面墨卡托切片对应Web Mercator那一套带_c后缀的是经纬度直投切片坐标系还是CGCS2000。你在ArcGIS Pro里加载时如果地图框用的是地理坐标系加_w的服务会有轻微拉伸这是正常的投影转换不是数据错了。想要完全对齐把地图框的坐标系设成和切片一致就行。3. 网页端零门槛看历史影像完整操作路径3.1 找到时间轴多时相专题的入口逻辑网页端是整个多时相影像专题里门槛最低的部分不需要Key不需要装软件打开就能用。入口的逻辑一般是这样的在天地图的主界面上找到专题或者图层切换的入口里面会有一个和多时相影像相关的专题选项点进去之后界面上会出现一条时间轴或者一排年份按钮。拖动或者点击年份底图就会切换到对应时期的影像。这里有几个操作细节值得说一下。第一切换年份时地图的中心点和缩放级别会保留所以你想对比某个具体位置先定位好再切年份不要来回重新找。第二不同区域的可用期次不一样有些地方只能切三四个年份有些地方多一些这取决于该区域历史影像的获取情况不是功能故障。第三缩放级别会影响你看到的内容放得太大可能看到的是插值后的模糊块放得太小又看不出变化一般建议放到能看清道路和建筑轮廓的层级再判断。注意网页端看到的是经过处理和匀色的影像用于判读和浏览没问题但如果你要拿去做正式的成果图或者面积量算建议下载原始影像或者通过服务接口获取避免因为色彩处理引入误判。3.2 坐标拾取与实地对照怎么做得更准天地图坐标拾取是热词里出现频率很高的一个词原因很实在很多人手上只有经纬度或者只有一张现场照片需要知道照片里那个位置到底对应哪个坐标。网页端的工具条里通常会有坐标拾取相关的功能不同版本入口位置略有差异如果实在找不到还有一个笨办法——在地图上把位置放到屏幕中心然后从URL里读中心点和级别参数也能大致反推坐标。实际操作里我更推荐两段式做法。先用网页端做粗略定位把可疑区域缩到一个小区块然后再用桌面GIS精确叠图。原因很简单网页端没有精确的量算工具靠肉眼点选误差几十米很正常。如果这件事关系到工程量的认定几十米是不能接受的。还有一个小技巧比对的时候不要只看影像本身把注记图层打开。多时相影像切换时注记是叠加在上面的路名、村名、地标名不变你会更容易判断这块地到底是哪儿不至于因为影像色调变化而认错位置。3.3 影像比对与留档的正确姿势做变化核查的人最后都要落到留证据上。我的习惯是在同一位置、同一缩放级别、同一视角下把两期影像分别截图然后并排拼在一起在图上标注坐标、截取日期、影像来源。这套做法看着土但在报告和评审里最管用因为评审人不需要自己去复现一眼就能看到差别。如果你要做正式一点的东西建议把坐标、期次、判断结论整理成表表格里至少包含这五列点位编号、经纬度、对比期次、变化类型、备注。有了这个表后面无论是复核还是补充材料都有据可依。字段说明示例点位编号自定的唯一编号P-001经纬度建议保留6位小数116.407400, 39.904200对比期次参与对比的年份2016 / 2024变化类型新增建设、拆除、水体变化等新增硬化地面备注需要说明的疑点2021年影像云量较大4. ArcGIS / ArcGIS Pro 加载天地图参数清单与实操4.1 一张表看懂天地图 WMTS 各图层服务arcgis加载在线天地图的安装步骤详解是个老话题但新版本天地图的服务命名和参数一直有人在问。核心其实就一张表。天地图的WMTS服务遵循OGC标准请求参数包括SERVICE、REQUEST、VERSION、LAYER、STYLE、TILEMATRIXSET、FORMAT、TILEMATRIX、TILEROW、TILECOL最后带上你的tk。图层服务路径后缀LAYER 参数常见用途矢量底图/vec_w/wmtsvec常规底图矢量注记/cva_w/wmtscva路名、地名影像底图/img_w/wmtsimg影像判读影像注记/cia_w/wmtscia影像上的地名地形晕渲/ter_w/wmtster地形起伏展示地形注记/cta_w/wmtscta地形图上的地名带_w的是球面墨卡托切片带_c的是经纬度切片。做叠加分析的时候一个很实用的技巧是底图和注记分开加载两层因为注记层通常是透明的叠在影像上不会遮挡地物而且开关起来很方便。gispro显示天地图地形图的需求就是把ter_w和cta_w两层一起加上再把地形晕渲的透明度调到70%左右地名就会清楚地浮在上面。4.2 ArcGIS Pro 里连 WMTS 的两条路径在ArcGIS Pro里接天地图最稳的一条路是走WMTS服务器连接。大致流程是在目录窗格或插入选项卡里找到添加服务器连接类的功能新建一个WMTS服务器连接URL填到.../img_w/wmts这一层然后在弹出的认证信息里把tk作为参数带上或者直接把?tk你的Key拼在URL末尾。连接建立后服务里的图层会列出来直接拖进地图就能用。另一条路是XYZ瓦片图层。如果你用的版本里有这个入口可以直接填入瓦片模板URL格式和下面这段一样把{z}、{y}、{x}留成占位符程序会自动替换。这条路的好处是不用走WMTS的能力文档解析坏处是部分版本对子域名轮询的支持没那么好需要你手动指定一个固定的子域名比如t0。https://t0.tianditu.gov.cn/img_w/wmts?SERVICEWMTSREQUESTGetTileVERSION1.0.0LAYERimgSTYLEdefaultTILEMATRIXSETwFORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk你的KEY注意ArcGIS Pro 的地图框坐标系如果设成了某个地方坐标系加载天地图这种大范围底图时会出现明显的扭曲这是投影转换的必然结果不是数据错误。做全国范围的展示用Web墨卡托做局部精确叠加再考虑换到地方坐标系。4.3 让历史影像对比变成可复现的工程一个人偶尔看两眼用网页端就够了。但如果是团队作业或者需要长期跟踪就得把它工程化。我的做法是在ArcGIS Pro的工程里建一个专门的分组图层把不同期次的影像各放一层命名规则统一成年份_区域_影像然后把除当前期次以外的图层全部关掉。这样切年份只需要勾选图层可见性不需要重新加载服务速度很快而且工程模板可以复制给同事用。再进一步可以把每期影像的元信息整理成一个表用日期字段驱动图层的时间滑块功能。ArcGIS Pro的时间感知图层可以在时间轴上播放配合多期影像做动态演示汇报的时候非常直观。这个功能不需要额外的插件只是需要在图层属性里指定时间字段并启用时间。5. 二次开发用天地图 API 做一个历史影像对比小工具5.1 最小可运行的地图初始化代码写代码这部分我假设你已经拿到了浏览器端的Key并且配好了域名白名单。下面这段是能直接跑起来的最小示例用的是Leaflet因为它的体积小、依赖少做对比工具最合适。// 天地图影像底图 影像注记Leaflet 1.9.x const TK 替换成你自己的浏览器端Key; const map L.map(map, { center: [39.9042, 116.4074], zoom: 12, minZoom: 1, maxZoom: 18 }); function tdLayer(path, layerName) { return L.tileLayer( https://t{s}.tianditu.gov.cn/${path}/wmts?SERVICEWMTSREQUESTGetTile VERSION1.0.0LAYER${layerName}STYLEdefaultTILEMATRIXSETw FORMATtilesTILEMATRIX{z}TILEROW{y}TILECOL{x}tk${TK}, { subdomains: [0, 1, 2, 3, 4, 5, 6, 7], maxZoom: 18, minZoom: 1 } ); } const baseLayer tdLayer(img_w, img).addTo(map); const annoLayer tdLayer(cia_w, cia).addTo(map);子域名数组里那八个编号是用来轮询请求的能把并发压力分散开加载速度会明显好一些。这一点在官方示例里不一定写得很显眼但实测下来差别不小。5.2 时间轴切换的实现思路多时相的核心是切换。实现上不要每次切换都去重建整个地图那样会闪、会丢中心点。正确的做法是把每一期影像做成一个图层对象切换时只做移除旧的、添加新的中心点和缩放级别完全不动。// scenes 里按时间顺序填入官方多时相服务提供的各期图层路径 // 具体的服务路径与图层名以官方文档公布为准 const scenes [ { year: 2016, path: img_w, layer: img }, { year: 2020, path: img_w, layer: img }, { year: 2024, path: img_w, layer: img } ]; let current null; function showScene(scene) { if (current) { map.removeLayer(current); } current tdLayer(scene.path, scene.layer); current.setZIndex(1); current.addTo(map); // 注记层需要重新提到最上面否则会被影像盖住 annoLayer.bringToFront(); } showScene(scenes[scenes.length - 1]);这里有一个坑要提前说每次添加新图层都要把注记层提到最上面否则新加的影像会把注记压在底下看上去就是地名突然没了。这个现象很容易被误判成服务故障其实只是层级顺序问题。5.3 卷帘对比的实现思路除了按时间切换还有一种更直观的展示方式是卷帘对比两个影像上下叠着中间一条可拖动的分隔线线的左边是A期右边是B期。实现上不需要复杂的库用CSS的裁剪路径就能做出来。// 上层影像用 clip-path 裁掉分隔线右侧的部分 const topLayer tdLayer(img_w, img).addTo(map); topLayer.setZIndex(5); let split 50; // 分隔线位置单位% function applyClip() { const target topLayer.getContainer(); if (target) { target.style.clipPath inset(0 ${100 - split}% 0 0); } } map.on(move zoom, applyClip); // 地图移动后重新应用防止被重置 applyClip(); // 拖动分隔条时更新 split 并调用 applyClip()卷帘的好处是同一屏幕、同一视角、同时看到两期做汇报演示的时候效果比来回切换要好得多因为观众的视线不用在两个画面之间跳。实际操作里要注意的是地图缩放或者平移之后裁剪样式可能会被瓦片容器重建覆盖掉所以要在move和zoom事件里重新应用一次。6. 常见问题速查与避坑清单6.1 鉴权类问题速查表鉴权类问题占了新手提问的绝大多数我整理成一张表对着查基本能定位。报错或现象可能原因处理办法返回code: 301001 / 非法keyKey拼写错误、类型不匹配、白名单未配置逐项核对Key、类型、白名单天地图key调用地图时好时坏配额接近上限被限流查看控制台用量错峰或升级浏览器端正常桌面端报错用了浏览器端Key换服务端Key并配置IP白名单HTTPS页面加载失败页面协议与服务协议不一致统一使用HTTPS地址部分图层报错其他正常对应服务未勾选控制台补勾服务还有一点必须提醒不要把Key硬编码在前端代码里长期暴露。浏览器端Key虽然有域名白名单保护但白名单是可以被绕过的最稳妥的做法是通过自己的后端做一层代理转发把Key放在服务端前端只请求自己的接口。这多花半小时能省掉后面Key被滥用导致服务不可用的麻烦。6.2 显示与偏移类问题偏移问题我前面讲过原理这里说具体表现。如果影像和你的矢量数据整体错开一个固定距离方向一致那基本是坐标系不匹配通常是拿GCJ-02的坐标点直接叠上去了。如果错位是不规则的、不同位置偏移量不一样那更可能是投影设置的问题检查地图框坐标系和切片坐标系是否一致。如果只在某些层级明显、放大之后又对上了那多半是缩放层级取整的问题属于正常现象。还有一个新手常问的现象切到某个年份后画面出现马赛克或者空白块。这通常不是功能坏了而是那一期的影像在该区域没有覆盖或者是瓦片还在加载中。先等几秒再缩小一级看整体覆盖范围。6.3 性能与配额加载慢的问题八成出在两件事上一是没有配置子域名轮询所有请求都打到一个域名上并发上不去二是一次性加载了太多图层底图、注记、地形、多期影像全开着浏览器渲染压力大。我的习惯是最多同时开三层需要对比的时候用卷帘或者切换别硬堆。配额方面免费额度是有上限的具体数值以控制台显示和官方文档为准。做开发的时候建议把失败重试做成退避策略不要一报错就立刻重发那样很容易把额度刷完。另外切片请求是逐个瓦片计数的地图缩放到很高级别、范围又拉得很大的时候一次浏览可能就消耗掉几百次调用这个账要算清楚。提示开发阶段可以用浏览器开发者工具的网络面板看一下实际发出的瓦片请求数量和状态码分布比对着控制台数字猜要高效得多。很多配额异常消耗的问题一看请求列表就明白了。我在实际使用中的体会是天地图这套东西的价值不在于它比商业服务更强而在于它把能查、能用、能对接这三件事的门槛降到了很低。多时相影像专题最实用的地方是让你在一个免费、稳定的入口里把过去和现在放在同一块屏幕上比较。真正决定成果质量的还是你有没有把坐标系、期次、判读标准这几件事做扎实。工具只是把路铺平了怎么走还得自己看脚下。