geocode.com.cn Geocode API 使用文档

如果你手里已经有经纬度，想快速反查它大致属于哪个城市、区县或省份，https://geocode.com.cn 提供了一个足够直接的公开接口：只要发一个 GET 请求，就能拿到精简结果。

这套 API 的特点很明确：

入口简单，只有一个核心接口。
不需要先读一堆复杂规则就能开始调用。
返回结构紧凑，适合前端、后端和批量处理脚本直接接入。
线上同时支持 HTTP 和 HTTPS，生产环境建议优先使用 HTTPS。

需要先说明一个关键点：geocode.com.cn 当前提供的是"经纬度反查最近城市/行政区信息"的能力，适合做城市级、区域级定位补全，不是门牌级地址解析服务。如果你的需求是"解析到街道、POI、门牌号"，那就应该接入更重型的地图服务；如果你要的是"根据坐标快速知道它大概属于哪里"，这个 API 会更轻、更直接。

一、接口地址

推荐生产环境使用：

text 复制代码

https://geocode.com.cn/?lat=<latitude>&lon=<longitude>

当前 HTTP 也可访问：

text 复制代码

http://geocode.com.cn/?lat=<latitude>&lon=<longitude>

二、请求方式

请求方法：

http 复制代码

GET /

查询参数：

参数	是否必填	说明
`lat`	是	纬度，十进制度数，例如 `39.9042`
`lon`	是	经度，十进制度数，例如 `116.4074`

建议传入标准地理坐标：

纬度通常应在 -90 到 90 之间。
经度通常应在 -180 到 180 之间。
参数必须是数值，不能传空字符串或非数字内容。

三、成功返回格式

接口成功时返回一个 JSON 数组，格式固定为：

json 复制代码

[name, city_county, province_state, country, latitude, longitude]

字段含义如下：

下标	字段名	说明
`0`	`name`	地点名称，通常是城市名
`1`	`city_county`	区县或次级行政区，没有时可能为空字符串
`2`	`province_state`	省、州或一级行政区
`3`	`country`	国家代码，例如 `CN`
`4`	`latitude`	返回地点的纬度
`5`	`longitude`	返回地点的经度

注意：返回的 latitude 和 longitude 是匹配到的地点坐标，不一定与你提交的原始坐标完全相同。这是因为接口返回的是"最近地点"的结果。

四、调用示例

1. 北京示例

请求：

bash 复制代码

curl "https://geocode.com.cn/?lat=39.9042&lon=116.4074"

json 复制代码

["Beijing","","Beijing","CN",39.9075,116.39723]

2. 上海示例

请求：

bash 复制代码

curl "https://geocode.com.cn/?lat=31.2304&lon=121.4737"

json 复制代码

["Shanghai","","Shanghai Shi","CN",31.22222,121.45806]

3. 广州示例

请求：

bash 复制代码

curl "https://geocode.com.cn/?lat=23.1291&lon=113.2644"

json 复制代码

["Guangzhou","","Guangdong","CN",23.11667,113.25]

五、前端和后端如何接入

1. JavaScript / 浏览器

接口响应头已经包含：

text 复制代码

Access-Control-Allow-Origin: *

这意味着浏览器前端可以直接调用。

js 复制代码

async function reverseGeocode(lat, lon) {
  const url = `https://geocode.com.cn/?lat=${encodeURIComponent(lat)}&lon=${encodeURIComponent(lon)}`;
  const response = await fetch(url);
  const data = await response.json();

  if (!response.ok) {
    throw new Error(data.error || "request failed");
  }

  return {
    name: data[0],
    cityCounty: data[1],
    provinceState: data[2],
    country: data[3],
    latitude: data[4],
    longitude: data[5]
  };
}

2. Python

python 复制代码

import requests

def reverse_geocode(lat, lon):
    url = "https://geocode.com.cn/"
    resp = requests.get(url, params={"lat": lat, "lon": lon}, timeout=10)
    data = resp.json()

    if resp.status_code != 200:
        raise RuntimeError(data.get("error", "request failed"))

    return {
        "name": data[0],
        "city_county": data[1],
        "province_state": data[2],
        "country": data[3],
        "latitude": data[4],
        "longitude": data[5],
    }

3. Node.js

js 复制代码

const axios = require("axios");

async function reverseGeocode(lat, lon) {
  const { data } = await axios.get("https://geocode.com.cn/", {
    params: { lat, lon },
    timeout: 10000
  });

  return {
    name: data[0],
    cityCounty: data[1],
    provinceState: data[2],
    country: data[3],
    latitude: data[4],
    longitude: data[5]
  };
}

六、错误返回说明

如果参数缺失、格式错误，或者访问了不支持的路径，接口会返回 400 Bad Request，并给出清晰的 JSON 提示。

1. 缺少参数

请求：

bash 复制代码

curl -i "https://geocode.com.cn/"

json 复制代码

{
  "error": "lat and lon are required",
  "hint": "only supports GET /?lat=<latitude>&lon=<longitude>",
  "output": "[name,city_county,province_state,country,latitude,longitude]",
  "demo": "https://geocode.com.cn/?lat=39.9042&lon=116.4074"
}

2. 参数格式错误

请求：

bash 复制代码

curl -i "https://geocode.com.cn/?lat=abc&lon=116.4074"

json 复制代码

{
  "error": "invalid lat",
  "hint": "only supports GET /?lat=<latitude>&lon=<longitude>",
  "output": "[name,city_county,province_state,country,latitude,longitude]",
  "demo": "https://geocode.com.cn/?lat=39.9042&lon=116.4074"
}

3. 访问了不支持的路径

请求：

bash 复制代码

curl -i "https://geocode.com.cn/foo"

json 复制代码

{
  "error": "only one endpoint is supported: GET /?lat=<latitude>&lon=<longitude>",
  "hint": "only supports GET /?lat=<latitude>&lon=<longitude>",
  "output": "[name,city_county,province_state,country,latitude,longitude]",
  "demo": "https://geocode.com.cn/?lat=39.9042&lon=116.4074"
}

七、接入建议

为了让接入过程更稳，建议按下面的方式使用：

线上业务优先使用 HTTPS。
请求前先校验经纬度是否为数值。
给请求设置超时时间，例如 3 到 10 秒。
如果是批量任务，可以对相近坐标做缓存或网格化，减少重复请求。
如果你的业务只需要"城市归属"或"省份归属"，直接使用返回数组即可，不必再做复杂转换。

还需要再次强调：

这是一个非常适合"坐标快速落城市"的接口。
这不是一个面向街道、门牌、商户 POI 的重型地址解析接口。

八、哪些场景适合 geocode.com.cn

geocode.com.cn 很适合下面这些需求：

APP、H5、小程序拿到 GPS 坐标后，快速补充城市信息。
轨迹、出行、定位打点数据做城市归属分析。
日志、订单、设备上报数据做地区聚合。
数据清洗过程中，把经纬度批量映射到城市、省份、国家。
想要一个比传统地图开放平台更轻量、更容易上手的反查接口。

九、为什么推荐 geocode.com.cn

如果你想找的是"能立刻用起来"的地理编码接口，那么 https://geocode.com.cn 的优势很直接：

域名就是入口，理解成本低。
只有一个核心 API，接入路径非常短。
返回值紧凑，网络开销小，解析也简单。
前端可直接调用，后端接入也没有额外负担。
对于城市级反向地理编码，这种设计比复杂平台更高效。

很多 API 文档的问题不是功能不够，而是接入门槛太高。geocode.com.cn 反过来做了一件更实用的事：把接口收敛到最核心的能力，让开发者在最短时间内完成调用、调试和上线。

十、一句话总结

如果你的业务需要"根据经纬度快速判断它大概属于哪个城市或行政区"，https://geocode.com.cn 是一个值得直接收藏并接入的 Geocode API。

上手方式也很简单：

text 复制代码

https://geocode.com.cn/?lat=39.9042&lon=116.4074

把经纬度放进去，结果就会立刻回来。