当前位置： 首页 > news >正文

【和风天气】开始使用：天气API请求 城市编码API请求

news 2026/4/18 1:48:30

开始使用

欢迎使用和风天气开发服务，本篇文档将介绍一些基本概念和文档索引，便于你快速开始以及了解和风天气开发服务是如何运行的。

帐号 

你需要注册一个帐号，用于管理你的项目、凭据、财务等事宜。请参考帐号管理。

配置API和SDK 

在请求数据之前，需要一些准备工作：

  • 创建项目和凭据用来管理你的API。
  • 了解身份认证，和风天气支持两种身份认证方式：JSON Web Token (JWT) 以及 API KEY。
  • 获取API Host，这是你独立的API请求地址。
  • 如何发送API请求。
  • 安装和配置 iOS SDK 或 Android SDK。

开发 

我们提供了详尽的开发文档以及实用资料，可以帮助开发者更高效的完成工作。

另一方面，最佳实践介绍了一些常见做法和经验，以便你能够快速的、稳定的获取你需要的数据。

费用 

和风天气的计费方式为按量计费，并采用阶梯价，意味着你的请求量越多，单价越低，并且当你停止使用时，你不需要支付任何费用。请参考定价和计费方式和支付。

如果你的请求量较多，你也可以使用节省计划来大幅降低你的成本，了解节省计划。

对于中国大陆地区的用户，我们的价格已经包含增值税，如需要开具增值税发票请参考增值税发票。

帮助和支持 

你可以点击网页顶部的放大镜按钮去搜索需要的资料，或查看常见问题。99%的疑问可以在文档中找到答案。

你也可以提交工单，我们的技术专家将尽快帮助你。

前往控制台 - 工单

条款 

为了提供一个更加公平、高效、合规的开发环境，你需要同意我们的各项服务条款，并在许可证允许的范围内使用和风天气开发服务。参考条款。

 

 

 

API Host

API Host是开发者独立的API地址，用于取代传统的公共API地址，这将提供更高的安全性和保护开发者的隐私。

对于每个开发者帐号来说，API Host都是独立、唯一的，同时API Host也是身份认证的一部分，这意味着即使开发者的凭据泄露了，盗用者如果不知道API Host也是无法请求数据的。

查看你的API Host 

你可以在控制台-设置中查看你的API Host，API Host 看起来像是：

abc1234xyz.def.qweatherapi.com

使用API Host 

你需要将API Host粘贴至API请求URL或SDK的配置文件中，请参考：

  • 如何发送API请求
  • 安装和配置 iOS SDK
  • 安装和配置 Android SDK

API 配置

了解如何发送一个API请求。

现在，我们假设你已经创建了项目和凭据，准备开始创建一个完整的API请求吧。

请求URL 

通常来讲，一个完整的API请求URL由scheme，host，path，path parameters和query parameters组成：

https://abcxyz.qweatherapi.com/airquality/v1/station/{LocationID}?lang=en
\___/   \____________________/\____________________/\___________/\______/
scheme           host                  path              path      queryparams     params
  • scheme: 仅支持HTTPS协议。
  • host: 开发者的API Host，请在控制台-设置中查看。
  • path: API的请求路径（或称之为API端点、Endpoint）。
  • path params: 路径参数均为必选参数。
  • query params: 查询参数，包括必选和可选参数，多个查询参数使用&分割。

提示：你必须对参数中的特殊字符进行URL编码。

添加身份认证 

我们在上一步创建了一个API请求URL，现在需要为它添加身份认证以便服务器可以识别我们的身份。了解身份认证。

JWT

在请求标头中添加如下内容：

Authorization: Bearer eyJhbGciOiAiRWREU0EiLCJraWQiOiAiQUJDRDEyMzQifQ.eyJpc3MiOiJBQkNEMTIzNCIsImlhdCI6MTcwMzkxMjQwMCwiZXhwIjoxNzAzOTEyOTQwfQ.MEQCIFGLmpmAEwuhB74mR04JWg_odEau6KYHYLRXs8Bp_miIAiBMU5O13vnv9ieEBSK71v4UULMI4K5T9El6bCxBkW4BdA

API KEY

在请求标头中添加如下内容：

X-QW-Api-Key: ABCD1234EFGH

Gzip 

请注意，和风天气开发服务的API均使用Gzip进行了压缩，这将极大的减少网络流量，加快请求。因此，当你在开发过程中，需要对返回的数据进行解压。请参考最佳实践-Gzip。

构建完整的API请求 

你可以用熟悉的开发语言构建最终的API请求，这里使用curl获取北京实时天气为例：

# 将下列占位符替换为你的实际值:
# abcxyz.qweatherapi.com → 你的 API Host
# 1234.ABCD.5678 → 你生成的 JWT
# ABCD1234EFGH → 你的 API KEY# JWT 身份认证curl --compressed \
-H 'Authorization: Bearer 1234.ABCD.5678' \
'https://abcxyz.qweatherapi.com/v7/weather/now?location=101010100'# API KEY 身份认证curl --compressed \
-H "X-QW-Api-Key: ABCD1234EFGH" \
'https://abcxyz.qweatherapi.com/v7/weather/now?location=101010100'

对于大部分开发者来说，构建一个API URL并非难事，但我们仍然强烈建议你阅读最佳实践-优化请求文档，了解发送API请求的一些常见问题和经验。

 

当然，为了得到天气，需要得知城市编码；而一般无法记住城市编码，因此需要通过城市搜索API，将文本（如“北京”“上海”“Shanghai”等）获取到对应的城市编码。

城市搜索API

平台: API iOS Android

城市搜索API提供全球地理位位置、全球城市搜索服务，支持经纬度坐标反查、多语言、模糊搜索等功能。

天气数据是基于地理位置的数据，因此获取天气之前需要先知道具体的位置信息。使用城市搜索，可获取到该城市的基本信息，包括城市的Location ID（你需要这个ID去查询天气），多语言名称、经纬度、时区、海拔、Rank值、归属上级行政区域、所在行政区域等。

另外，城市搜索也可以帮助你在你的APP中实现模糊搜索，用户只需要输入1-2个字即可获得结果。

请求路径 

/geo/v2/city/lookup

参数 

查询参数

  • location(必选)需要查询地区的名称，支持文字、以英文逗号分隔的经度,纬度坐标（十进制，最多支持小数点后两位）、LocationID或Adcode（仅限中国城市）。例如 location=北京 或 location=116.41,39.92

模糊搜索，当location传递的为文字时，支持模糊搜索，即用户可以只输入城市名称一部分进行搜索，最少一个汉字或2个字符，结果将按照相关性和Rank值进行排列，便于开发或用户进行选择他们需要查看哪个城市的天气。例如location=bei，将返回与bei相关性最强的若干结果，包括黎巴嫩的贝鲁特和中国的北京市

重名，当location传递的为文字时，可能会出现重名的城市，例如陕西省西安市、吉林省辽源市下辖的西安区和黑龙江省牡丹江市下辖的西安区，此时会根据Rank值排序返回所有结果。在这种情况下，可以通过adm参数的方式进一步确定需要查询的城市或地区，例如location=西安&adm=黑龙江

  • adm城市的上级行政区划，可设定只在某个行政区划范围内进行搜索，用于排除重名城市或对结果进行过滤。例如 adm=beijing

如请求参数为location=chaoyang&adm=beijing时，返回的结果只包括北京市的朝阳区，而不包括辽宁省的朝阳市

如请求参数仅为location=chaoyang时，返回的结果包括北京市的朝阳区、辽宁省的朝阳市以及长春市的朝阳区

  • range搜索范围，可设定只在某个国家或地区范围内进行搜索，国家和地区名称需使用ISO 3166 所定义的国家代码。如果不设置此参数，搜索范围将在所有城市。例如 range=cn
  • number返回结果的数量，取值范围1-20，默认返回10个结果。
  • lang多语言设置，请阅读多语言文档，了解我们的多语言是如何工作、如何设置以及数据是否支持多语言。

请求示例 

curl -X GET --compressed \
-H 'Authorization: Bearer your_token' \
'https://your_api_host/geo/v2/city/lookup?location=beij'

请将your_token替换为你的JWT身份认证，将your_api_host替换为你的API Host

返回数据 

返回数据是JSON格式并进行了Gzip压缩。

{"code":"200","location":[{"name":"北京","id":"101010100","lat":"39.90499","lon":"116.40529","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"10","fxLink":"https://www.qweather.com/weather/beijing-101010100.html"},{"name":"海淀","id":"101010200","lat":"39.95607","lon":"116.31032","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"15","fxLink":"https://www.qweather.com/weather/haidian-101010200.html"},{"name":"朝阳","id":"101010300","lat":"39.92149","lon":"116.48641","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"15","fxLink":"https://www.qweather.com/weather/chaoyang-101010300.html"},{"name":"昌平","id":"101010700","lat":"40.21809","lon":"116.23591","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"23","fxLink":"https://www.qweather.com/weather/changping-101010700.html"},{"name":"房山","id":"101011200","lat":"39.73554","lon":"116.13916","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"23","fxLink":"https://www.qweather.com/weather/fangshan-101011200.html"},{"name":"通州","id":"101010600","lat":"39.90249","lon":"116.65860","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"23","fxLink":"https://www.qweather.com/weather/tongzhou-101010600.html"},{"name":"丰台","id":"101010900","lat":"39.86364","lon":"116.28696","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"25","fxLink":"https://www.qweather.com/weather/fengtai-101010900.html"},{"name":"大兴","id":"101011100","lat":"39.72891","lon":"116.33804","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"25","fxLink":"https://www.qweather.com/weather/daxing-101011100.html"},{"name":"延庆","id":"101010800","lat":"40.46532","lon":"115.98501","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"33","fxLink":"https://www.qweather.com/weather/yanqing-101010800.html"},{"name":"平谷","id":"101011500","lat":"40.14478","lon":"117.11234","adm2":"北京","adm1":"北京市","country":"中国","tz":"Asia/Shanghai","utcOffset":"+08:00","isDst":"0","type":"city","rank":"33","fxLink":"https://www.qweather.com/weather/pinggu-101011500.html"}],"refer":{"sources":["QWeather"],"license":["QWeather Developers License"]}
}
  • code 请参考状态码
  • location.name 地区/城市名称
  • location.id 地区/城市ID
  • location.lat 地区/城市纬度
  • location.lon 地区/城市经度
  • location.adm2 地区/城市的上级行政区划名称
  • location.adm1 地区/城市所属一级行政区域
  • location.country 地区/城市所属国家名称
  • location.tz 地区/城市所在时区
  • location.utcOffset 地区/城市目前与UTC时间偏移的小时数，参考详细说明
  • location.isDst 地区/城市是否当前处于夏令时。1 表示当前处于夏令时，0 表示当前不是夏令时。
  • location.type 地区/城市的属性
  • location.rank 地区评分
  • location.fxLink 该地区的天气预报网页链接，便于嵌入你的网站或应用
  • refer.sources 原始数据来源，或数据源说明，可能为空
  • refer.license 数据许可或版权声明，可能为空
http://www.jsqmd.com/news/658363/

相关文章：

  • 不同材质工件（塑胶/金属/镀锌件）喷漆加工的工艺差异
  • 基于STM32LXXX的无线收发芯片（SI4463-C2A-GMR）应用程序设计
  • 健康管理没有局外人!深圳国商联帮你把健康握在手里
  • 从代码孤岛到智能协同，揭秘头部科技公司如何用LLM+GitOps实现PR通过率提升67%、交付周期压缩42%，你团队缺的不是工具，而是这1套协作协议
  • 周红伟：RAG 与知识检索
  • 从零实现MDP：用Python代码拆解马尔可夫决策过程核心算法
  • AI编程全栈实战课：网站开发+多端封装+微信小程序+支付上线，零基础一站式学会落地
  • 基于STM32LXXX的无线收发芯片（CC2530F256RHAR）应用程序设计
  • 如何高效实现B站视频智能转文字：bili2text技术深度解析与实战指南
  • 7种RAG查询预处理方案详解：告别检索效果差，提升回复质量！
  • 腾讯AI 应用开发 面经，一次过
  • Unity游戏窗口自定义：实现标题栏与边框的动态控制
  • PyCharm里用pip装Seaborn总失败？试试这3种更稳的安装方式（含Anaconda对比）
  • 为什么会选择美国洛杉矶代理IP来做TikTok业务？
  • 超详细！Hermes Agent 一键部署全流程指南，轻松上手不踩坑
  • 接口返回blob，如何实现小程序下载
  • 告别Batch Size焦虑：用PyTorch手把手实现Group Normalization（附完整代码）
  • 如何获取并定制化订货系统源码以适应企业需求？
  • Java转大模型，8个月上岸
  • HPH构造一看就懂！核心部件和工作原理
  • 2026国产适合企业的Ai智能体平台选型推荐：架构师视角下的非侵入式集成与提效避坑指南
  • 一份就懂的PyOpenGL实战指南，从零到一构建3D小游戏！
  • ESP32编译固件内存信息解读
  • **剪枝模型实战：用Python实现轻量化神经网络优化，从理论到代码全解析**
  • OpenClaw为何疯狂“吃”Token？
  • 有赞对接金蝶云星空全链路技术解决方案
  • ceph的monitor集群和osd集群
  • Siemens 6DS1311-8AE 总线驱动
  • 鱼眼双目测距实战：从OpenCV标定到SGBM匹配的完整流程解析
  • Vue 3 技术演进全景