手把手调通维智天气查询 API(附完整返回解析 + 申请试用流程)

0 阅读6分钟

一、接口速览

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 在应用创建后生成。

试用申请三步走:

  1. 打开 WAYZ IoT Board

  2. 注册/登录:支持短信登录(手机号 + 验证码)、密码登录、LDAP 登录;首次使用点击“免费注册”。登录页如下:

  3. 进入控制台“我的应用”页面,点击右上角 “+ 新应用申请”,提交后即可在应用列表中看到生成的 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"}

六、几个容易踩的坑

  1. 新旧地址别混用:老项目可能搜到 maps/proxy/v1/weather,新项目统一用 location/scenario/v1/weather。

  2. city 传的是城市编码,不是城市名:北京 110000、武汉 420100,不是 "北京" 或 "beijing"。

  3. 所有字段都是字符串:temperature、daytemp 等返回的是 "16" 这样的字符串,前端展示没问题,做数值计算时要先转换。

  4. 鉴权在 URL 上:access_key 是 Query Param,生产环境注意不要把带 KEY 的完整 URL 打到日志里。

  5. 先看 infocode 再解析数据:失败时 lives/forecasts 可能不存在,直接取数组会报错。


七、如何申请试用

如果前面的步骤已经跑通,想正式接入到自己的项目里,可以按下面的入口申请试用:

  • 申请入口(注册 / 创建应用):WAYZ IoT Board
  • 申请步骤:注册账号 → 创建应用 → 获得 KEY → 调用接口
  • 注意事项:KEY 属于敏感凭证,建议按环境(测试 / 生产)分别创建应用,便于后续额度管理和问题排查。

结语

整体来看,WAYZ 天气查询 API 的接入成本很低:一个 GET 请求 + 一个 KEY,实时天气和未来预报一次搞定,返回字段也足够覆盖大多数业务场景。建议先用 Postman 按本文步骤调通,确认字段符合预期后再写进业务代码。如果在申请或调试过程中遇到问题,可以直接加技术群交流。