地名检索

Open-Meteo

地理与位置可直接调用免费

在线调试上游文档

调用地址

GET https://api.blueworkshop.top/api/v1/geocode

无需鉴权支持 CORS 每 IP 每分钟 60 次；结果缓存 86400 秒

在线调试

请求会发送到本站接口

当前请求：https://api.blueworkshop.top/api/v1/geocode

请求参数

参数	类型	默认值	说明
`name`必填	string	-	地名关键词，例如北京、Tokyo。示例：`北京`
`count`	int	`5`	返回结果数量，1 到 20。示例：`5`
`language`	枚举：zh / en / ja / fr / de / es / ru	`zh`	返回语言的偏好。示例：`zh`

请求示例

cURL

curl "https://api.blueworkshop.top/api/v1/geocode?name=%E5%8C%97%E4%BA%AC&count=5&language=zh"

JavaScript

const res = await fetch("https://api.blueworkshop.top/api/v1/geocode?name=%E5%8C%97%E4%BA%AC&count=5&language=zh");
const data = await res.json();
console.log(data);

响应示例

{
  "ok": true,
  "data": {
    "results": [
      {
        "id": 1816670,
        "name": "北京",
        "latitude": 39.9075,
        "longitude": 116.39723,
        "country": "中国",
        "country_code": "CN",
        "timezone": "Asia/Shanghai",
        "population": 18960744
      }
    ]
  },
  "meta": {
    "endpoint": "geocode",
    "cached": false
  }
}

成功时返回 JSON 信封：ok 表示是否成功，data 为数据，meta.cached 表示是否命中本站缓存。图片类接口直接返回二进制图片。

错误响应

HTTP	错误码	说明
400	`missing_param` / `invalid_param`	缺少参数或参数格式不正确，响应会带上出错参数名。
404	`not_found`	接口不存在，或上游没有找到对应资源。
405	`method_not_allowed`	请求方法与接口要求不一致。
429	`rate_limited`	请求过于频繁，响应头 Retry-After 给出建议等待秒数。
502	`upstream_error` / `upstream_rate_limited`	上游服务异常或触发限流。
504	`timeout`	上游请求超时。

接口说明

基于 Open-Meteo 的地理编码服务，把城市、地区名称转换为经纬度坐标，可直接配合天气接口使用。

例如先调用本接口查询北京的坐标，再把 latitude/longitude 传给天气接口。结果缓存 1 天，减少上游请求。