开发者指南：URL 参数、嵌入与 JavaScript API

三条入口

入口	什么时候用	从这里开始
查询字符串	你手上有一个坐标、一个数值或一整份清单，想让计算器打开时就已经填好—— 来源可以是电子表格、CMS 字段、邮件里的链接或一个 <a href>。	参数速查
iframe 嵌入	这个计算器该出现在你自己的页面或内网里，但你不想重做一遍。 加上 embed=1，页头、正文和页脚就都不见了。	嵌入方法
window.Geo	你要的是数字，不是界面——批量处理坐标文件、构建步骤中调用， 或者在同一个引擎上搭你自己的 UI。	JavaScript API

查询字符串 API

参数只在页面加载时读取一次。工具不认识的内容一律忽略， 所以 URL 里混进一个多余参数绝不会弄坏计算器——它只是不起作用，工具照常使用默认值。 参数值必须做 URL 编码，而 + 会被解码为空格，所以粘贴进来的坐标清单可以安全传递。

一旦你开始操作某个工具，它就用 history.replaceState 改写自己的地址， 因此刷新、收藏或复制地址栏，都能原样复现屏幕上的状态。这个过程不会重新加载页面， 也不会多出一条可以往回点的历史记录。在嵌入模式下，工具完全不碰 URL。

坐标类工具

如果没有传 mode，标签页就由你实际传了的参数来推断： 一对经纬度选中正算标签页，一对东西坐标选中反算标签页，带 text 则选中批量。

下面四个链接是现成可用的——点开，答案就在屏幕上：

• utm-coordinate-converter?lat=43.642567&lon=-79.387139 正算：17T 带，东坐标 630,084.301 m，北坐标 4,833,438.586 m。
• utm-coordinate-converter?e=630084.301&n=4833438.586&zone=17N 反算：回到北纬 43.642567°、西经 79.387139°。
• utm-coordinate-converter?mode=batch&dir=inv&zone=17N&text=… 批量：输入一条格网坐标，输出一条经纬度。
• unit-converter?value=100&from=usft&to=m 单位：100 美国测量英尺 = 30.48006096 m。

单位换算器

长度键： m ft usft in cm km yd ch lk rd fur fath mi nmi lea vara.
面积键： m2 ft2 acre ha usacre km2 mi2 yd2 are rood sqch sqrd section township.
角度键： deg dms rad grad milN milA turn amin asec.

你不一定要传 mode。如果没传，换算器会查 from 这个键， 自动切到包含它的那一类，所以 ?value=1&from=acre&to=ha 不用再给别的提示就会落到面积标签页。无法识别的单位键会被忽略，改用该类别的默认单位。

实时构建一个链接

改一下字段，下面的 URL 会立刻更新。按 预览 把这个 URL 原样加载到下方的框架里， 效果就等同于你自己页面上的一枚 iframe 会显示的内容。

把计算器嵌入你自己的页面

加上 embed=1，页面会隐藏除计算器以外的一切：没有页头、没有面包屑、 没有大标题、没有正文、没有页脚。剩下的就是工具卡片本身，按它的自然高度呈现，随时可以放进框架。

<iframe
  src="https://coordcalc.com/utm-coordinate-converter?embed=1&lat=43.642567&lon=-79.387139"
  title="UTM 与经纬度互转"
  width="100%" height="560" style="border:1px solid #cfd6e0;border-radius:12px"
  loading="lazy"></iframe>

有三个细节值得保留。给框架一个 title，因为屏幕阅读器会朗读它， 而没有标题的框架在无障碍上是一条死路。用 loading="lazy"， 这样长页面下方的工具在你滚动到它之前不产生任何开销。最后，按最高的那个标签页来设定框架高度， 而不是按你链接过去的那个，这样在框架内切换标签页时不会冒出滚动条。

被嵌入的工具与独立页面是同一份文档，所以每种行为都保留：标签页可以切换、 结果随输入实时重算、复制链接能生成 URL、批量标签页照旧导出 CSV。 它同时也很安静——嵌入环境下的计算不写 Cookie、不发请求，也绝不触碰父页面。 请在承载嵌入的页面上保留一个指向该工具的可见链接；没有任何署名的孤立框架，是我们唯一请你避免的用法。

实时示例——下面的框架就是 utm-coordinate-converter?embed=1&lat=43.642567&lon=-79.387139：

JavaScript API — window.Geo

所有计算器都运行在同一个共享库上，它被内联进每个工具页面，并以全局 Geo 暴露。 打开任意一个工具，进到浏览器控制台，它就在那里：

> Geo.utmForward(43.642567, -79.387139)
{ zone: 17, north: true, band: "T", centralMeridian: -81,
  easting: 630084.3008341495, northing: 4833438.585674161,
  convergence: 1.1133056360734274, scaleFactor: 0.9998080873147939 }

它是无依赖、不访问 DOM 的纯 ES5，所以同一个文件在 Node 下也能用： 库的结尾是 module.exports = Geo，这意味着构建脚本或测试框架 可以直接把它从页面里取出来 require。

函数

算例

下面的每个数值都由这个库自己算出；在任何工具页面上跑同样的代码，得到的就是同样的数字。

// 多伦多 CN 塔：经纬度 -> UTM
var u = Geo.utmForward(43.642567, -79.387139);
Geo.fmt(u.easting, 3);      // "630,084.301"
Geo.fmt(u.northing, 3);     // "4,833,438.586"
u.zone + u.band;            // "17T"
Geo.fmt(u.scaleFactor, 7);  // "0.9998081"

// 再转回去
var g = Geo.utmInverse(630084.301, 4833438.586, 17, true);
Geo.fmt(g.lat, 8);          // "43.64256700"
Geo.fmt(g.lon, 8);          // "-79.38713900"

// MGRS
Geo.mgrsForward(43.642567, -79.387139, 5).mgrs;   // "17TPJ3008433438"
Geo.mgrsInverse("17TPJ3008433438");               // { lat, lon, zone: 17, band: "T", … }

// 椭球距离与方位角，多伦多到北京
var d = Geo.vincentyInverse(43.642567, -79.387139, 39.906111, 116.3974);
Geo.fmt(d.distance, 1);      // "10,616,473.2"  metres
Geo.fmt(d.initialBearing, 4);// "347.9204"      degrees
d.converged;                 // true

// 由地块各角点算地表面积与周长
var parcel = [[43.641000, -79.388000], [43.641000, -79.385517],
              [43.642356, -79.385517], [43.642356, -79.388000]];
var a = Geo.polygonArea(parcel);
Geo.fmt(a.area, 1);          // "30,184.0"      square metres
Geo.fmt(a.perimeter, 2);     // "702.01"        metres
a.orientation;               // "counter-clockwise"

polygonArea 需要多解释一句。它把多边形环投影到以自身重心为中心的切平面上 （也就是 localPlane 返回的东西），所以得到的是地表面积而不是 Web 墨卡托面积， 并且在任何纬度都成立。顶点的绕行方向无所谓：鞋带公式取的是绝对值， orientation 只是告诉你绕行方向是哪一边。 perimeter 由各边上的 Vincenty 距离累加而成，因此是椭球长度； geodesicPerimeter 告诉你 Vincenty 是否在每一条边上都收敛。

常量

Geo.UNITS 带着这些工具赖以建立的换算系数，调用方无需重述： M_PER_FT 0.3048、M_PER_MI 1609.344、 M_PER_NM 1852、HA_M2 10000、ACRE_M2 4046.8564224， 以及 SQFT_PER_M2 10.763910416709722。椭球参数在 Geo.A（6378137 m）和 Geo.F（1 / 298.257223563）上，对应 WGS84。

精度，以及一个注意事项

横轴墨卡托级数用的是公开那一套，反算用牛顿迭代求解而不是截断的反向级数。 对照 PROJ——pyproj 与 QGIS 背后的参考实现——在从赤道到北纬 78°、经度 0° 到 180° 的测试点上，东坐标优于 0.1 mm，北坐标优于 0.9 mm。 正算再反算的往返闭合差在几纳米量级，也就是说，这已经是双精度浮点的极限。

注意事项是 MGRS。17TPJ3008433438 这样的五位参考号命名的不是一个点， 而是一个 1 m 见方的方格，mgrsInverse 返回的是该方格的西南角。 转成 MGRS 再转回来，你应该预期落点离出发点最多差约 1.4 m——这是格式使然，不是错误。 改用六位数字，方格就是 0.1 m 见方。

参考值

南半球的北坐标包含 10,000,000 m 的假北向平移值，与测量图纸上印的一致。

注意事项、限制与条款

• 不需要密钥，没有配额。没有什么需要注册，也没有什么需要计量。页面是静态文件， 每次计算都在浏览器里完成，所以工具慢只说明设备慢，而不是账号被限流。
• 什么都不上传。没有任何坐标、数值或粘贴的清单会离开这个页面。 请求只用于文档本身、一份样式表和一个小脚本。
• 仅二维平面。该库在 WGS84 椭球上按二维工作，不考虑局部基准平移、 似大地水准面模型或美国州平面投影带；这些场合请用 州平面坐标转换器， 并对照 EPSG 代码查询核对你文件里实际带的投影。
• 仅供参考，不能替代标准。结果用于核对与规划。 凡涉及施工、边界或采购的事项，都要对照该项工作适用的规范确认。
• 署名。欢迎嵌入，但请保留一个指回该工具的可见链接。 不要把计算器当作你自己的作品，也不要把修改过的副本换个名字重新托管， 以暗示它能算某些它其实算不了的东西。
• 版本。该库是逐页内联的，而不是从共享文件加载，所以你复制走的页面 在站内工具更新后仍能继续工作。代价是修复不会自动到达副本—— 如果你依赖它，请重新复制一份。

相关计算器

常见问题

可以直接用链接预填计算器吗？

可以。每个工具都会从查询字符串读取状态。?lat=43.642567&lon=-79.387139 打开 UTM 转换器时已经换算完毕；?value=100&from=usft&to=m 打开单位换算器并停在测量英尺换算上。缺失或无法识别的参数会被忽略，工具回退到自己的默认值。

需要 API 密钥吗？有调用频率限制吗？

都不需要。页面是静态的，每次计算都在访问者的浏览器里完成，因此没有什么需要授权，也没有什么是需要计量的。任何坐标都不会被发送到服务器。

怎么把计算器嵌入我自己的页面？

加上 embed=1，再用 iframe 加载这个 URL。它会隐藏页头、面包屑、正文和页脚，单坐标类工具的框架高度约 520 px。框架内一切照常工作，包括切换标签页和导出 CSV。

window.Geo 是什么？

是内联在工具页面里的共享大地测量库，基于 WGS84 椭球。它暴露 utmForward、utmInverse、mgrsForward、mgrsInverse、vincentyInverse、polygonArea、parseAngle 等函数，以及单位常量。它是无依赖的 ES5，同时通过 module.exports 导出，可在 Node 中使用。

UTM 转换的精度如何？

对照 PROJ，从赤道到北纬 78° 的测试点上东坐标优于 0.1 mm、北坐标优于 0.9 mm，正算再反算的往返闭合差在几纳米量级。反算是用牛顿迭代求解的，不是截断的反向级数。

为什么 MGRS 往返换算会差出一米左右？

因为五位参考号命名的是一个 1 m 见方的方格而不是一个点，反算返回的是该方格的西南角。偏差可达约 1.4 m。用六位数字，方格就是 0.1 m 见方。