首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「地理坐标计算」接口介绍

数据鱼API「地理坐标计算」接口介绍

原创
作者头像
用户12862874
发布于 2026-11-21 21:29:23
发布于 2026-11-21 21:29:23
50
举报

接口简介

「地理坐标计算」(geo)是数据鱼API平台的本地地理计算接口,Base 路径 /api/geo,共 11 个端点,覆盖三类能力:坐标系批量转换、距离与方位测量、以及网格编码与几何判断。所有计算在服务端本地完成,不依赖第三方地图服务。

坐标系支持 WGS84、GCJ02、BD09 三套系统,可在任意两者之间双向转换,单次最多 200 个点。距离计算采用 haversine 球面公式,地球半径取 6371000 米,同时给出公里数、方位角与十六方位中文名;还可由起点、方位角与距离反推目标点。几何部分提供最近点查询、多边形面积与点包含判断,编码部分支持 Geohash 与 Maidenhead 两种网格。

GCJ02 转回 WGS84 使用 10 轮迭代逼近,官方标注精度优于 0.1 米;境外坐标不做 GCJ 偏移。接口只处理坐标与几何关系,不涉及行政区划、边界主张或归属判断,输出的是数学结果而非地理政治结论。数据鱼API把这类能力做成无状态端点,方便地图、配送、围栏类业务直接调用。

端点总览

方法

路径

说明

鉴权

GET

/api/geo/ping

健康检查

否

GET

/api/geo/stats

服务与算法清单

是

POST

/api/geo/convert

坐标系批量转换

是

POST

/api/geo/measure

两点距离、方位与中点

是

POST

/api/geo/destination

由方位与距离推算目标点

是

POST

/api/geo/nearest

最近点查询

是

POST

/api/geo/polygon

多边形面积与点包含

是

GET

/api/geo/geohash/encode

Geohash 编码

是

GET

/api/geo/geohash/decode

Geohash 解码

是

GET

/api/geo/maidenhead/encode

Maidenhead 网格编码

是

GET

/api/geo/maidenhead/decode

Maidenhead 网格解码

是

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013。GET 与 POST 均可调用,POST 支持 JSON body 或表单;坐标、点集、多边形等数组参数必须放在 JSON body 中,作为 query 字符串传入会触发 4002。

响应为 {"code":0,"msg":"success","data":{...}}。缺少必填参数返回 4001,格式或取值非法、数量超限返回 4002,取值不在支持列表返回 4003,目标未收录返回 4004。文档保留了 5031/5032 上游不可用错误,但这些端点的算法均在本地执行,正常部署下不会因外部数据源失败。

坐标统一使用 [经度, 纬度] 顺序,经度在前、纬度在后,范围为 -180~180 与 -90~90。stats 返回可用坐标系、算法清单、地球半径与各项数量上限,可作为调用前的能力探测。

核心端点详解

坐标系转换 convert

参数

类型

必填

默认值

说明

coords

array

是

—

坐标数组 [[lng,lat],...],最多 200 点

from

string

否

—

源坐标系:wgs84、gcj02、bd09

to

string

否

—

目标坐标系:wgs84、gcj02、bd09

返回 from、to、total 与 list。list 每项含 index、input、output(输出保留 6 位小数)与 transformed;源与目标相同时 transformed 为 false,坐标原样返回。from/to 在文档中标为可选,但未给出默认值,实际调用应显式传入。

两点测量 measure

参数

类型

必填

默认值

说明

from

array

是

—

起点 [lng,lat]

to

array

是

—

终点 [lng,lat]

返回 distance_m、distance_km、bearing_deg、bearing_name 与 midpoint。方位角按起点指向终点计算,bearing_name 是十六方位中文名,例如「东南」。

目标点 destination

参数

类型

必填

默认值

说明

from

array

是

—

起点 [lng,lat]

bearing

number

是

—

方位角,0~360 度

distance_m

number

是

—

距离,最大值 20015000(半地球周长)

返回 output 目标点、distance_m 与 bearing。它与 measure 互为逆运算,往返结果在 0.1 度舍入范围内一致。

最近点 nearest

参数

类型

必填

默认值

说明

origin

array

是

—

查询原点 [lng,lat]

points

array

是

—

候选点,最多 500 个,元素为 [lng,lat] 或 {id,lng,lat}

k

int

否

1

返回数量,1~50;超过候选数时返回全部

radius_m

number

否

—

半径过滤,0 < r ≤ 20015000

候选点对象写法可用 lon 代替 lng,id 可选且原样返回。结果按未舍入的原始距离升序排列,距离相同按原始下标升序;输出距离保留一位小数。返回 total、matched、returned、k、radius_m 与 list,每项含 index、id、point、distance_m、distance_km、bearing_deg、bearing_name。origin 与候选点必须使用同一坐标系,接口不做转换。

多边形 polygon

参数

类型

必填

默认值

说明

polygon

array

是

—

顶点数组,至少 3 个,最多 500 个

test

array

否

—

待判断点集,最多 200 个

返回 vertices、closed、area_m2、area_km2 与 contains。contains 每项含 point 与 contained;面积按环计算,1 公里见方范围的误差小于 0.3%。

网格编码

Geohash 编码接收 lng、lat 与可选 precision,返回 hash、precision、lng、lat,解码接收 hash。Maidenhead 编码参数相同,返回 locator 而非 hash;解码接收 locator,返回 center、bounds.sw、bounds.ne 与 precision。这两组工具适合做网格索引、位置模糊化与业余无线电定位。

数据与限制

  • 批量转换上限 200 点,多边形顶点上限 500、测试点上限 200,最近点候选上限 500、k 上限 50。
  • 距离基于球面模型而非椭球,长距离结果与大地测量值存在米级到百米级差异;不适合测绘级用途。
  • GCJ02 为中国境内地图加密偏移,境外点不做偏移;GCJ02 转 WGS84 为迭代逼近,官方精度优于 0.1 米。
  • nearest 不做坐标系转换,混用 WGS84 与 GCJ02 会产生数百米偏差;radius_m 必须大于 0。
  • 多边形面积按输入环计算,closed 表示输入是否显式闭合;判断点包含时按射线法处理。
  • 所有端点无状态、无缓存、无持久化,不保存提交的坐标。

典型使用场景

地图打点:把设备采集的 WGS84 轨迹批量转成 GCJ02 或 BD09,消除在国内地图上显示的偏移。

配送与选址:用 measure 算直线距离,用 nearest 从门店列表中筛出指定半径内的最近网点。

围栏判断:把配送区域画成多边形,用 polygon 批量判断订单坐标是否落区,并计算区域面积。

空间索引:用 Geohash 前缀做附近查询的粗筛,或把经纬度转成 Maidenhead 网格用于无线电通联定位。

注意事项

coords 在参数表中被标为 string,但实际要求二维数组,传字符串会返回 4002。这是文档描述与实现的偏差,调用时应直接传 JSON 数组;from、to 则是坐标系名称字符串。

坐标顺序固定为经度在前。把 [lat,lng] 反过来传,接口不会报错,但会得到错误的位置甚至越界错误;接入前应统一封装参数构造函数。

坐标系混用是最常见的错误来源。convert 负责转换,measure、destination、nearest、polygon 都假定输入已处于同一坐标系;跨系统混算的距离和围栏结果不可信。

nearest 的 k 超过 50 会直接返回 4002,不是自动截断;radius_m 上限为 20015000 米,超出同样报参数非法。

Geohash 与 Maidenhead 的 precision 未在文档中给出默认值与上下限,不同精度对应不同网格尺寸,生产环境应显式传值并做边界校验。

接口输出的是几何计算结果,不构成行政区划、边界或主权归属的判断依据。涉及地图展示与合规时,仍需使用具备测绘资质的底图与审图号,数据鱼API不承担底图合规责任。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 坐标系转换 convert
    • 两点测量 measure
    • 目标点 destination
    • 最近点 nearest
    • 多边形 polygon
    • 网格编码
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档