天地图 API 逆地理编码接口详解：从经纬度到结构化地址

做地图类应用时经常会碰到这样的场景：设备上报过来一串经纬度，而界面上需要显示「北京市西城区西什库大街31号院」这种人类能读懂的地址。把坐标翻译成位置描述，这个动作在地理信息领域叫做逆地理编码（Reverse Geocoding）。天地图提供的逆地理服务 API 就是专门解决这个问题的——它是一类简单的 HTTP/HTTPS 接口，输入一个坐标点（经纬度），返回结构化的地址信息。

下面把这个接口的请求参数、返回字段和真实的 JSON 返回结构完整梳理一遍，并附上一段可以直接运行的 JavaScript 调用示例。开始之前需要先在天地图官网申请 Key，也就是请求参数里的 tk。

一、请求接口与参数

接口以 GET 方式调用，地址形如 http://api.tianditu.gov.cn/geocoder（也支持 HTTPS），主要参数如下：

除了上述参数，请求还需要带上 type=geocode 指定服务类型，坐标信息则以 postStr 参数传入，格式是一个 JSON 字符串。

请求示例

http://api.tianditu.gov.cn/geocoder?postStr={'lon':116.37304,'lat':39.92594,'ver':1}&type=geocode&tk=您的密钥

二、响应结构

接口返回 JSON，顶层包含三个字段：

返回示例

以坐标 116.37304, 39.92594 为例，返回结果如下：

{
    "result": {
        "formatted_address": "北京市西城区西什库大街31号院23东方开元信息科技公司",
        "location": {
            "lon": 116.37304,
            "lat": 39.92594
        },
        "addressComponent": {
            "address": "西什库大街31号院23",
            "city": "北京市西城区",
            "road": "大红罗厂街",
            "poi_position": "东北",
            "address_position": "东北",
            "road_distance": 49,
            "poi": "东方开元信息科技公司",
            "poi_distance": "38",
            "address_distance": 38
        }
    },
    "msg": "ok",
    "status": "0"
}

result 字段说明

addressComponent 字段说明

location 字段说明

三、JavaScript 调用示例

下面是一段可以直接用的调用封装，把坐标转成地址对象，并统一处理了 HTTP 错误和业务状态码：

// 天地图逆地理编码：坐标 -> 结构化地址
const TK = '你的天地图密钥';

async function reverseGeocode(lon, lat) {
    const postStr = JSON.stringify({ lon, lat, ver: 1 });
    const url = 'http://api.tianditu.gov.cn/geocoder'
        + '?postStr=' + encodeURIComponent(postStr)
        + '&type=geocode'
        + '&tk=' + TK;

    const res = await fetch(url);
    if (!res.ok) throw new Error('HTTP ' + res.status);

    const data = await res.json();
    // 注意：status 是字符串，"0" 才代表成功
    if (data.status !== '0') throw new Error(data.msg || '逆地理编码失败');

    return {
        address: data.result.formatted_address,   // 完整地址
        component: data.result.addressComponent,  // 行政区、道路、POI 等
        location: data.result.location            // 回传的坐标
    };
}

reverseGeocode(116.37304, 39.92594).then(console.log);

四、几个容易踩的坑

• 参数名不一致。文档表格里密钥参数写作 appkey，但示例 URL 和实际接口用的是 tk，照表格写会一直报鉴权错误。
• 距离字段拼写不一致。文档表格里写的是 address_distince、poi_distince、road_distince（distince 少了一个 a），而接口真实返回的是 address_distance、poi_distance、road_distance。取值时以真实返回为准。
• status 是字符串不是数字。返回的 "status": "0" 带引号，用 === 0 判断会永远失败，应该判断 === '0'。
• 坐标须为经纬度数值。lon 为经度、lat 为纬度，顺序不能颠倒；天地图使用 CGCS2000 坐标系，若手上是其他坐标系的点，需先做转换再查询。
• Key 有配额限制。生产环境建议在服务端做一层缓存与转发，避免前端密钥暴露和配额浪费。

小结

天地图的逆地理编码服务接口本身非常简单：一个 GET 请求，四个核心参数，返回 JSON 中包含完整地址、行政区划、最近道路与 POI 以及距离方位信息，足以支撑「定位当前位置」「地址回显」这类常见需求。真正需要注意的是文档与实现之间的几处细节差异——密钥参数叫 tk 不叫 appkey、距离字段是 distance 不是 distince、状态码是字符串而非数字。把这几点处理妥当，接入过程基本不会遇到额外阻力。

官方文档地址：http://lbs.tianditu.gov.cn/server/geocoding.html