iOS/Android

城市搜索与管理
支持全球城市快捷检索,提供多语言支持与智能补全,方便用户快速添加和管理关注的城市。
城市搜索 translate 与 GeoPosition 经纬度定位,获取 Location Key,对接全球 300 万+ 城市。
华风爱科定位搜索 API 提供全球 300 万+ 城市的 RESTful 天气接口入口,支持城市名称文字搜索(translate)与经纬度 GeoPosition 定位,返回 Location Key 供后续气象数据 API 调用。由中国气象局授权品牌与 AccuWeather 全球数据能力提供支撑。
基于定位API的移动端应用场景示例

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

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

获取 Location Key 后,即可获取该位置相关的各类气象数据集(如实况、预报、指数、雷达等)。
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|
| 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 |
| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|---|
| 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 | 可用数据集 | - |
| 参数 | 类型 | 说明 | 数据形式示例 |
|---|---|---|---|
|
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 | 可用数据集 | - |
# 文字搜索(标准能力)
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()
[
{
"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 定位(标准能力)
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()
{
"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"
]
}
X-Gw-API-Key: YOUR_API_KEY,避免 Key 出现在 URL 日志中。