全国天气预报API怎么接入城市名称城市ID与经纬度如何选

发布时间：2026-08-11 00:56 点击：1051次

接入天气预报 API 时，先按业务已有信息选择城市名称、城市 ID、天气代号、经纬度或 IP，五种定位参数任选其一即可；生产系统更适合保存稳定标识，并把更新时间、业务状态和无天气信息分开处理。

天气查询前要准备什么

极速数据的全国天气预报 API 文档提供“天气预报查询”和“获取城市”两个接口。天气查询地址是 https://api.jisuapi.com/weather/query，支持 GET、POST；获取城市列表使用 https://api.jisuapi.com/weather/city。两个接口都需要在服务端携带 APPKEY。

正式接入前建议先确定三个问题：

用户输入的是自然语言城市，还是系统内部已经保存了城市标识；
业务只展示当前天气，还是还要使用最高温、最低温、风力、湿度和生活指数等字段；
查询失败时，是允许用户重新选城市，还是使用上一份成功结果并标明更新时间。

这些问题决定参数、缓存键和异常页面怎么设计。天气数据具有时间属性，不能只判断“有值”，还要让 updatetime 参与展示和缓存判断。

city、cityid、citycode、location 和 ip 怎么选

文档列出的五种定位参数都不是必填项，但说明中明确“以上参数任选其一”。因此，请求不能五项都空，也不应把多个相互冲突的定位值同时传入。

参数	适合场景	接入注意点
`city`	搜索框、客服工具等直接接收城市名称	用户输入可能有同名或简称，需保留重新选择入口
`cityid`	已使用极速数据城市列表建立映射	可作为内部查询键，避免每次依赖名称匹配
`citycode`	业务已有城市天气代号	先确认代码体系一致，不要与其他地区编码混用
`location`	地图、定位设备已取得经纬度	格式为纬度在前、经度在后，中间用英文逗号分隔
`ip`	只有访问 IP、只需粗粒度定位	IP 推断结果不等于用户当前精确位置，应允许手动修正

如果是首次接入，可先调用城市列表接口，把 cityid、parentid、citycode 和 city 保存为本地映射。用户仍可按名称搜索，但实际天气请求使用已经确认的 cityid。如果产品天然掌握坐标，例如门店或设备位置，则直接使用 location 更符合原始数据来源。

最小请求怎么写

下面的示例只展示请求结构，没有发起真实调用。APPKEY 应从服务端环境变量或密钥服务读取，不要写进前端代码、仓库或日志。

GET https://api.jisuapi.com/weather/query?appkey=YOUR_APPKEY&cityid=YOUR_CITY_ID

使用城市名称时要做 UTF-8 URL 编码。官方文档给出的请求示例使用城市“安顺”：

GET https://api.jisuapi.com/weather/query?appkey=YOUR_APPKEY&city=%E5%AE%89%E9%A1%BA

后端处理可以按以下顺序进行：

读取并校验定位参数
  -> 发送 HTTPS 请求并设置超时
  -> 判断 HTTP 状态和响应能否解析为 JSON
  -> 判断业务状态
  -> 校验 result 与关键字段
  -> 保存数据更新时间和本次拉取时间

不要把网络成功直接等同于天气查询成功。HTTP 200 只表示服务端返回了响应，城市不存在、没有对应天气信息或鉴权失败仍需要在 JSON 业务层判断。

返回结果应该保存哪些字段

文档中的当前天气字段包括 city、cityid、citycode、date、week、weather、temp、temphigh、templow、humidity、pressure、windspeed、winddirect、windpower 和 updatetime 等。接入时不必把所有字段都塞进一张业务表，可按用途分层：