一、接口速览
WAYZ 天气查询 API 用于按城市编码查询实时天气或未来预报,底层对接权威气象数据源,开发者只需一个 HTTP GET 请求即可拿到结构化的 JSON。
|
项目
|
说明
|
| --- | --- |
|
请求方式
|
GET
|
|
新地址(推荐)
|
https://api.newayz.com/location/scenario/v1/weather
|
|
旧地址(兼容)
|
https://api.newayz.com/maps/proxy/v1/weather
|
|
鉴权方式
|
URL Query Param 中传 access_key
|
|
数据格式
|
字符串 UTF-8;时间戳为 int64 毫秒级 Unix 时间戳
|
|
请求头
|
Content-Type: application/json
|
官方明确说明:新客户请使用新地址,旧地址目前仍兼容,但不建议新项目继续接入。
请求参数
|
参数
|
类型
|
必填
|
说明
|
| --- | --- | --- | --- |
|
access_key
|
String
|
是
|
申请应用后获得的 KEY,用于接口鉴权
|
|
city
|
Number
|
是
|
城市编码,例如北京市为 110000、武汉市为 420100
|
|
extensions
|
String
|
是
|
base:实时天气;all:预报天气
|
完整 URL 形式:
https://api.newayz.com/location/scenario/v1/weather?access_key=your_access_key&city=420100&extensions=base
二、先拿到 access_key:注册 + 创建应用
调用接口前必须有 KEY。WAYZ 的位置服务平台叫 WAYZ IoT Board(时空智能时代的物联定位底座),KEY 在应用创建后生成。
试用申请三步走:
-
打开 WAYZ IoT Board
-
注册/登录:支持短信登录(手机号 + 验证码)、密码登录、LDAP 登录;首次使用点击“免费注册”。登录页如下:
-
进入控制台“我的应用”页面,点击右上角 “+ 新应用申请”,提交后即可在应用列表中看到生成的
key:
拿到 KEY 后,把它填进上面 URL 的 your_access_key 位置,就可以开始调接口了。
三、Postman 完整配置步骤
1. 新建请求:打开 Postman → Ctrl + N → 选择 HTTP Request(或直接点“New” → HTTP Request)。
2. 选择方法:把默认的 GET 确认下来(本接口只用 GET)。
3. 填入 URL:
https://api.newayz.com/location/scenario/v1/weather?access_key=你的KEY&city=420100&extensions=base
填进地址栏后,Postman 会自动把 ? 后面的部分解析到 Params 标签页,确认三个参数都已勾选:
|
KEY
|
VALUE
|
| --- | --- |
|
access_key
|
你在 IoT Board 申请的 KEY
|
|
city
|
420100
|
|
extensions
|
base
|
4. 配置请求头:切到 Headers 标签,添加一行:
Content-Type: application/json
5. 发送:点击右侧蓝色 Send 按钮。
6. 查看结果:在下方 Response 区域选择 Body → Pretty → JSON,即可看到格式化后的响应。
四、返回结果展示与解析
以查询武汉(city=420100)为例,接口返回的 JSON 结构如下(示例数据来自官方文档,实际数值以你的请求返回为准):
{
"status": "1",
"count": "1",
"info": "OK",
"infocode": "10000",
"lives": [
{
"province": "湖北",
"city": "武汉市",
"adcode": "420100",
"weather": "雾",
"temperature": "16",
"winddirection": "东北",
"windpower": "≤3",
"humidity": "79",
"reporttime": "2023-03-22 14:47:54"
}
],
"forecasts": [
{
"city": "武汉市",
"adcode": "420100",
"province": "湖北",
"reporttime": "2023-03-22 14:47:54",
"casts": [
{
"date": "2023-03-22", "week": "3",
"dayweather": "小雨", "nightweather": "多云",
"daytemp": "14", "nighttemp": "14",
"daywind": "北", "nightwind": "北",
"daypower": "≤3", "nightpower": "≤3"
},
{
"date": "2023-03-23", "week": "4",
"dayweather": "小雨", "nightweather": "小雨",
"daytemp": "13", "nighttemp": "9",
"daywind": "北", "nightwind": "东北",
"daypower": "4", "nightpower": "4"
},
{
"date": "2023-03-24", "week": "5",
"dayweather": "小雨", "nightweather": "晴",
"daytemp": "8", "nighttemp": "7",
"daywind": "北", "nightwind": "北",
"daypower": "≤3", "nightpower": "≤3"
},
{
"date": "2023-03-25", "week": "6",
"dayweather": "晴", "nightweather": "小雨",
"daytemp": "14", "nighttemp": "11",
"daywind": "北", "nightwind": "北",
"daypower": "≤3", "nightpower": "≤3"
}
]
}
]
}
4.1 顶层状态字段
|
字段
|
含义
|
判断方式
|
| --- | --- | --- |
|
status
|
返回状态
|
"1" 成功,"0" 失败
|
|
count
|
返回结果总数目
|
字符串,如 "1"
|
|
info
|
状态信息
|
成功为 "OK"
|
|
infocode
|
状态说明码
|
"10000" 代表正确
|
|
lives
|
实时天气数组
|
Array<Live>
|
|
forecasts
|
预报天气数组
|
Array<Forecast>
|
工程建议:业务代码里不要只看 HTTP 状态码,务必同时校验 status == "1" 且 infocode == "10000",再做数据解析。
4.2 实时天气 lives 字段
|
字段
|
类型
|
说明
|
| --- | --- | --- |
|
province
|
String
|
省份名
|
|
city
|
String
|
城市名
|
|
adcode
|
String
|
区域编码
|
|
weather
|
String
|
天气现象(汉字描述)
|
|
temperature
|
String
|
实时气温,单位摄氏度
|
|
winddirection
|
String
|
风向描述
|
|
windpower
|
String
|
风力级别,单位级
|
|
humidity
|
String
|
空气湿度
|
|
reporttime
|
String
|
数据发布时间
|
4.3 预报天气 forecasts.casts 字段
把 extensions 改为 all 后会返回预报数据(文档示例中同时返回了 lives 和 forecasts,实际以接口返回为准)。casts 按**当天、第二天、第三天……**的顺序排列:
|
字段
|
说明
|
字段
|
说明
|
| --- | --- | --- | --- |
|
date
|
日期
|
week
|
星期几
|
|
dayweather
|
白天天气现象
|
nightweather
|
夜间天气现象
|
|
daytemp
|
白天温度
|
nighttemp
|
夜间温度
|
|
daywind
|
白天风向
|
nightwind
|
夜间风向
|
|
daypower
|
白天风力
|
nightpower
|
夜间风力
|
五、错误码速查表
调不通时先对照这张表,基本能覆盖 90% 的问题:
|
错误码
|
含义
|
典型原因
|
排查动作
|
| --- | --- | --- | --- |
|
400
|
参数异常
|
缺少参数、参数格式错误
|
检查 city、extensions 是否必填且合法
|
|
401
|
API 密钥认证失败
|
未传 KEY 或 KEY 错误
|
检查 access_key 是否填写正确
|
|
403
|
Appkey 权限异常
|
KEY 无该接口权限
|
确认应用是否已开通天气服务
|
|
404
|
无法解析
|
路径/scenario 不存在
|
确认使用的是新版 URL
|
|
429
|
请求次数超额
|
超出配额
|
查看控制台额度,或联系商务扩容
|
|
500
|
服务器异常
|
服务端问题
|
稍后重试,持续失败可反馈技术支持
|
常见报错体示例:
// 400
{"code": "400", "message": "no refdata provided"}
// 401
{"message": "No API key found in request"}
// 403
{"code": "403", "message": "Access key forbidden"}
// 404
{"code": "404", "message": "scenario not found"}
六、几个容易踩的坑
-
新旧地址别混用:老项目可能搜到
maps/proxy/v1/weather,新项目统一用location/scenario/v1/weather。 -
city传的是城市编码,不是城市名:北京110000、武汉420100,不是 "北京" 或 "beijing"。 -
所有字段都是字符串:
temperature、daytemp等返回的是"16"这样的字符串,前端展示没问题,做数值计算时要先转换。 -
鉴权在 URL 上:
access_key是 Query Param,生产环境注意不要把带 KEY 的完整 URL 打到日志里。 -
先看
infocode再解析数据:失败时lives/forecasts可能不存在,直接取数组会报错。
七、如何申请试用
如果前面的步骤已经跑通,想正式接入到自己的项目里,可以按下面的入口申请试用:
- 申请入口(注册 / 创建应用):WAYZ IoT Board
- 申请步骤:注册账号 → 创建应用 → 获得 KEY → 调用接口
- 注意事项:KEY 属于敏感凭证,建议按环境(测试 / 生产)分别创建应用,便于后续额度管理和问题排查。
结语
整体来看,WAYZ 天气查询 API 的接入成本很低:一个 GET 请求 + 一个 KEY,实时天气和未来预报一次搞定,返回字段也足够覆盖大多数业务场景。建议先用 Postman 按本文步骤调通,确认字段符合预期后再写进业务代码。如果在申请或调试过程中遇到问题,可以直接加技术群交流。