华风爱科天气API
首页 行业解决方案 产品介绍 天气资讯 开发文档 登录 注册
  • 概述
  • 开发标准与合规
  • 常见问题 (FAQ)
  • 实用资料 ›
    • MCP 配置参考
    • 多语言支持
    • 地区代码
    • 指数列表
    • 天气现象编码
    • 空气质量信息
    • 风向风速等级
    • 专业词汇表
    • 紫外线强度指数
  • 服务与隐私条款
  • 定位搜索 API
  • 实况天气 API
  • 逐日预报 API
  • 逐小时预报 API
  • 分钟级降水 API
  • 空气质量 API
  • 天气预警 API
  • 生活指数 API
  • 天文数据 API
  • 台风数据 API
  • 天气视频 API
  • 天气 MCP
首页/ 开发文档/ 定位搜索 API

定位搜索 API

城市搜索 translate 与 GeoPosition 经纬度定位,获取 Location Key,对接全球 300 万+ 城市。

产品概述

华风爱科定位搜索 API 提供全球 300 万+ 城市的 RESTful 天气接口入口,支持城市名称文字搜索(translate)与经纬度 GeoPosition 定位,返回 Location Key 供后续气象数据 API 调用。由中国气象局授权品牌与 AccuWeather 全球数据能力提供支撑。

  • ✓覆盖全球: 300 万+ 可搜索城市与区域
  • ✓坐标兼容: GeoLookup 支持 GCJ-02(中国大陆)与 WGS-84 坐标系
  • ✓多语言支持: 覆盖 100+ 语言和方言,支持本地化翻译
  • ✓智能搜索: 别名识别、自动补全、按重要性排序
产品展示

基于定位API的移动端应用场景示例

iOS/Android华风爱科天气API 城市搜索 Location Key 移动端示例

城市搜索与管理

支持全球城市快捷检索,提供多语言支持与智能补全,方便用户快速添加和管理关注的城市。

智能搜索城市列表
iOS/Android华风爱科 GeoPosition 经纬度定位 API 示例

精准定位服务

通过 GeoPosition 查询,将经纬度坐标精准解析为具体的行政区划与标准城市 Key,实现无缝对接。

Geo查询坐标解析
iOS/AndroidLocation Key 对接实况预报等天气 API 示例

基于位置的天气

获取 Location Key 后,即可获取该位置相关的各类气象数据集(如实况、预报、指数、雷达等)。

天气联动多数据集
想看真实请求效果?

登录控制台「示例中心 → 定位」可在线调试城市搜索与经纬度定位,查看完整响应。

打开示例中心
本页目录
  1. 快速开始
  2. 标准能力接口
  3. 文字搜索请求参数
  4. GeoPosition 请求参数
  5. 文字搜索返回字段
  6. GeoPosition 返回字段
  7. 代码示例 · 文字搜索
  8. 代码示例 · GeoPosition

快速开始

  1. 免费注册并完成开发者认证,获取 API Key(标准测试 Key 开通 30 天试用,每日 500 次免费调用,5 QPS)。
  2. 选择接口:城市名称用 /locations/v1/cities/translate;经纬度用 /locations/v1/cities/geoposition/search.json。
  3. 从响应中读取 Key(Location Key),即可调用实况天气、逐日预报等接口。

标准能力接口

GET 文字搜索(城市搜索)
https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false
GET GeoPosition 查询
https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn

文字搜索请求参数

参数名 类型 必填 默认值 说明 示例
apikey String 是 - API 密钥,见快速开始 YOUR_API_KEY
q String 是 - 搜索文本(城市名、邮编等) 北京
language String 否 en-us 响应语言 zh-cn
details String 否 false 是否返回完整位置数据 details = false
offset String 否 0 结果偏移量 0
alias String 否 Never 别名策略(Never/Always/NoOfficialMatch) Always

GeoPosition 请求参数

参数名 类型 必填 默认值 说明 示例
apikey String 是 - API 密钥 YOUR_API_KEY
q String 是 - 纬度,经度(建议保留 3 位小数) 39.9,116.3
language String 否 en-us 响应语言 zh-cn

文字搜索返回字段

参数 类型 说明 数据形式示例
Version
Int 版本号 1
Key
String 位置唯一标识(Location Key) 101924
Type
String 位置类型(City/POI 等) City
Rank
Int 位置排名优先级 10
LocalizedName
String 本地化名称 北京
EnglishName
String 英文名称 Beijing
PrimaryPostalCode
String 主要邮政编码 ""
Region ▶
Object 区域信息
3 个子字段
-
└─ ID
String 区域 ID ASI
└─ LocalizedName
String 区域本地化名称 亚洲
└─ EnglishName
String 区域英文名称 Asia
Country ▶
Object 国家信息
3 个子字段
-
└─ ID
String 国家 ID CN
└─ LocalizedName
String 国家本地化名称 中国
└─ EnglishName
String 国家英文名称 China
AdministrativeArea ▶
Object 行政区划信息
7 个子字段
-
└─ ID
String 行政区划 ID BJ
└─ LocalizedName
String 行政区划本地化名称 北京市
└─ EnglishName
String 行政区划英文名称 Beijing
└─ Level
Int 层级 1
└─ LocalizedType
String 本地化类型 市
└─ EnglishType
String 英文类型 Municipality
└─ CountryID
String 国家 ID CN
TimeZone ▶
Object 时区信息
5 个子字段
-
└─ Code
String 时区代码 CST
└─ Name
String 时区名称 Asia/Shanghai
└─ GmtOffset
Float GMT 偏移量 8
└─ IsDaylightSaving
Boolean 是否夏令时 false
└─ NextOffsetChange
String 下次偏移变更时间 null
GeoPosition ▶
Object 地理位置信息
3 个子字段
-
└─ Latitude
Float 纬度 39.919
└─ Longitude
Float 经度 116.413
└─ Elevation ▶
Object 高度信息
2 个子字段
-
└─ Metric ▶
Object 公制
3 个子字段
-
└─ Value
Float 数值 62
└─ Unit
String 单位 m
└─ UnitType
Int 单位类型 5
└─ Imperial ▶
Object 英制
3 个子字段
-
└─ Value
Float 数值 203
└─ Unit
String 单位 ft
└─ UnitType
Int 单位类型 0
IsAlias
Boolean 是否为别名 false
SupplementalAdminAreas
Array 补充行政区划 -
DataSets
Array 可用数据集 -

GeoPosition 返回字段

参数 类型 说明 数据形式示例
Version
Int 版本号 1
Key
String 位置唯一标识(Location Key) 57465
Type
String 位置类型(City/POI 等) City
Rank
Int 位置排名优先级 15
LocalizedName
String 本地化名称 海淀区
EnglishName
String 英文名称 Haidian District
PrimaryPostalCode
String 主要邮政编码 ""
Region ▶
Object 区域信息
3 个子字段
-
└─ ID
String 区域 ID ASI
└─ LocalizedName
String 区域本地化名称 亚洲
└─ EnglishName
String 区域英文名称 Asia
Country ▶
Object 国家信息
3 个子字段
-
└─ ID
String 国家 ID CN
└─ LocalizedName
String 国家本地化名称 中国
└─ EnglishName
String 国家英文名称 China
AdministrativeArea ▶
Object 行政区划信息
7 个子字段
-
└─ ID
String 行政区划 ID BJ
└─ LocalizedName
String 行政区划本地化名称 北京市
└─ EnglishName
String 行政区划英文名称 Beijing
└─ Level
Int 层级 1
└─ LocalizedType
String 本地化类型 市
└─ EnglishType
String 英文类型 Municipality
└─ CountryID
String 国家 ID CN
TimeZone ▶
Object 时区信息
5 个子字段
-
└─ Code
String 时区代码 CST
└─ Name
String 时区名称 Asia/Shanghai
└─ GmtOffset
Float GMT 偏移量 8
└─ IsDaylightSaving
Boolean 是否夏令时 false
└─ NextOffsetChange
String 下次偏移变更时间 null
GeoPosition ▶
Object 地理位置信息
3 个子字段
-
└─ Latitude
Float 纬度 39.985
└─ Longitude
Float 经度 116.307
└─ Elevation ▶
Object 高度信息
2 个子字段
-
└─ Metric ▶
Object 公制
3 个子字段
-
└─ Value
Float 数值 60
└─ Unit
String 单位 m
└─ UnitType
Int 单位类型 5
└─ Imperial ▶
Object 英制
3 个子字段
-
└─ Value
Float 数值 196
└─ Unit
String 单位 ft
└─ UnitType
Int 单位类型 0
SupplementalAdminAreas
Array 补充行政区划 -
DataSets
Array 可用数据集 -
IsAlias
Boolean 是否为别名 false
ParentCity ▶
Object 上级城市信息
3 个子字段
-
└─ Key
String 上级城市 ID 101924
└─ LocalizedName
String 上级城市本地化名称 北京
└─ EnglishName
String 上级城市英文名称 Beijing
SupplementalAdminAreas
Array 补充行政区划 -
DataSets
Array 可用数据集 -
上一篇服务与隐私条款 下一篇实况天气 API
>_ 代码示例
代码示例 · 文字搜索 通过城市名称获取 Location Key
Request
# 文字搜索(标准能力)
curl "https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false"
// 文字搜索(标准能力)
fetch('https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false')
  .then(response => response.json())
  .then(data => console.log(data));
import requests

# 文字搜索(标准能力)
url = "https://openapi.weathercn.com/locations/v1/cities/translate"
params = {'apikey': 'YOUR_API_KEY', 'q': '北京', 'language': 'zh-cn', 'details': 'false'}
response = requests.get(url, params=params)
print(response.json())
// 文字搜索(标准能力)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
<?php
// 文字搜索(标准能力)
$url = 'https://openapi.weathercn.com/locations/v1/cities/translate';
$params = http_build_query(['apikey' => 'YOUR_API_KEY', 'q' => '北京', 'language' => 'zh-cn', 'details' => 'false']);
$response = file_get_contents($url . '?' . $params);
print_r(json_decode($response, true));
?>
package main
import (
  "fmt"
  "io"
  "net/http"
)
func main() {
  url := "https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false"
  resp, _ := http.Get(url)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}
require 'net/http'
require 'json'

url = URI("https://openapi.weathercn.com/locations/v1/cities/translate")
params = {apikey: 'YOUR_API_KEY', q: '北京', language: 'zh-cn', details: 'false'}
url.query = URI.encode_www_form(params)
response = Net::HTTP.get_response(url)
puts JSON.parse(response.body)
let url = URL(string: "https://openapi.weathercn.com/locations/v1/cities/translate?apikey=YOUR_API_KEY&q=北京&language=zh-cn&details=false")!
let task = URLSession.shared.dataTask(with: url) { data, response, error in
    if let data = data { print(try? JSONSerialization.jsonObject(with: data)) }
}
task.resume()
Response 文字搜索返回示例(标准能力)
[
  {
    "Version": 1,
    "Key": "101924",
    "Type": "City",
    "Rank": 10,
    "LocalizedName": "北京",
    "EnglishName": "Beijing",
    "PrimaryPostalCode": "",
    "Region": {
      "ID": "ASI",
      "LocalizedName": "亚洲",
      "EnglishName": "Asia"
    },
    "Country": {
      "ID": "CN",
      "LocalizedName": "中国",
      "EnglishName": "China"
    },
    "AdministrativeArea": {
      "ID": "BJ",
      "LocalizedName": "北京市",
      "EnglishName": "Beijing",
      "Level": 1,
      "LocalizedType": "市",
      "EnglishType": "Municipality",
      "CountryID": "CN"
    },
    "TimeZone": {
      "Code": "CST",
      "Name": "Asia/Shanghai",
      "GmtOffset": 8.0,
      "IsDaylightSaving": false,
      "NextOffsetChange": null
    },
    "GeoPosition": {
      "Latitude": 39.919,
      "Longitude": 116.413,
      "Elevation": {
        "Metric": {
          "Value": 62.0,
          "Unit": "m",
          "UnitType": 5
        },
        "Imperial": {
          "Value": 203.0,
          "Unit": "ft",
          "UnitType": 0
        }
      }
    },
    "IsAlias": true,
    "SupplementalAdminAreas": [],
    "DataSets": [
      "AirQuality",
      "Alerts",
      "DailyAirQualityForecast",
      "DailyLocalIndices",
      "FutureRadar",
      "MinuteCast",
      "PremiumAirQuality"
    ]
  }
]
代码示例 · GeoPosition 通过经纬度获取 Location Key
Request
# GeoPosition 定位(标准能力)
curl "https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn"
// GeoPosition 定位(标准能力)
fetch('https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn')
  .then(response => response.json())
  .then(data => console.log(data));
import requests

# GeoPosition 定位(标准能力)
url = "https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json"
params = {'apikey': 'YOUR_API_KEY', 'q': '39.9,116.3', 'language': 'zh-cn'}
response = requests.get(url, params=params)
print(response.json())
// GeoPosition 定位(标准能力)
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
<?php
// GeoPosition 定位(标准能力)
$url = 'https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json';
$params = http_build_query(['apikey' => 'YOUR_API_KEY', 'q' => '39.9,116.3', 'language' => 'zh-cn']);
$response = file_get_contents($url . '?' . $params);
print_r(json_decode($response, true));
?>
package main
import (
  "fmt"
  "io"
  "net/http"
)
func main() {
  url := "https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn"
  resp, _ := http.Get(url)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}
require 'net/http'
require 'json'

url = URI("https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json")
params = {apikey: 'YOUR_API_KEY', q: '39.9,116.3', language: 'zh-cn'}
url.query = URI.encode_www_form(params)
response = Net::HTTP.get_response(url)
puts JSON.parse(response.body)
let url = URL(string: "https://openapi.weathercn.com/locations/v1/cities/geoposition/search.json?apikey=YOUR_API_KEY&q=39.9,116.3&language=zh-cn")!
let task = URLSession.shared.dataTask(with: url) { data, response, error in
    if let data = data { print(try? JSONSerialization.jsonObject(with: data)) }
}
task.resume()
Response GeoPosition 查询返回示例
{
  "Version": 1,
  "Key": "57456",
  "Type": "City",
  "Rank": 15,
  "LocalizedName": "朝阳区",
  "EnglishName": "Chaoyang District",
  "PrimaryPostalCode": "",
  "Region": {
    "ID": "ASI",
    "LocalizedName": "亚洲",
    "EnglishName": "Asia"
  },
  "Country": {
    "ID": "CN",
    "LocalizedName": "中国",
    "EnglishName": "China"
  },
  "AdministrativeArea": {
    "ID": "BJ",
    "LocalizedName": "北京市",
    "EnglishName": "Beijing",
    "Level": 1,
    "LocalizedType": "市",
    "EnglishType": "Municipality",
    "CountryID": "CN"
  },
  "TimeZone": {
    "Code": "CST",
    "Name": "Asia/Shanghai",
    "GmtOffset": 8.0,
    "IsDaylightSaving": false,
    "NextOffsetChange": null
  },
  "GeoPosition": {
    "Latitude": 39.916,
    "Longitude": 116.451,
    "Elevation": {
      "Metric": {
        "Value": 50.0,
        "Unit": "m",
        "UnitType": 5
      },
      "Imperial": {
        "Value": 164.0,
        "Unit": "ft",
        "UnitType": 0
      }
    }
  },
  "IsAlias": false,
  "ParentCity": {
    "Key": "101924",
    "LocalizedName": "北京",
    "EnglishName": "Beijing"
  },
  "SupplementalAdminAreas": [],
  "DataSets": [
    "AirQuality",
    "Alerts",
    "DailyAirQualityForecast",
    "DailyLocalIndices",
    "FutureRadar",
    "MinuteCast",
    "PremiumAirQuality"
  ]
}
☆
获取 API Key:请先免费注册并完成开发者认证,标准测试 Key 开通 30 天试用,每日 500 次免费调用(5 QPS)。
安全传参:建议通过 Header 传递密钥 X-Gw-API-Key: YOUR_API_KEY,避免 Key 出现在 URL 日志中。
©2015-2025 中国天气 All Rights reserved. 京ICP备16022777号-1