开发标准与合规

华风爱科开放 API 服务平台接口调用规范和要求

请您在开发前仔细逐条阅读以下开发规范,如违反以下标注为「必须项」的规则将有可能导致系统自动停用您的账号。

必须项

禁止未经允许的异常访问

禁止未经允许的异常访问,例如大规模压力测试等。合作方的异常访问行为,经评估会影响 API 正常工作或关键指标,在通知该合作方后,华风爱科有权临时停用该合作方的接口账号。

必须项

禁止以任何形式缓存定位数据

禁止以任何形式缓存定位数据。

必须项

不允许使用任何妨碍或影响华风爱科缓存数据的调用方式

不允许使用任何妨碍或影响华风爱科缓存数据的调用方式。(正常的,按照说明文档进行的调用,是不会影响缓存的,但有一些特殊技术是可以阻止或者影响缓存正常运行的,比如传递特定的 header 信息等。)

必须项

提交的 latitude 和 longitude 必须四舍五入至 3 位小数

使用经纬度定位时,提交的 latitude 和 longitude 必须四舍五入至 3 位小数,比如 q=39.921,116.469 是正确的,而不能传 q=39.9212,116.4691。

必须项

使用 GZIP

  • 使用 GZIP 可以减少传输到设备上的数据量;
  • 使用 GZIP 增加数据请求速度;
  • GZIP 数据压缩只需在调用的 HTTP 请求 Header 中增加 Accept-Encoding: gzip,deflate 即可启用;
  • 例如:无压缩时数据大小为 17695 字节;压缩后数据大小减少至 2958 字节;
必须项

避免所有设备在同一时间请求数据

  • 须避免所有设备在同一时间请求数据,举例而言,避免所有设备在每天 12 点 30 分同时请求刷新数据;
  • 可按照开机时间或 APP 启动时间计算开始时间,经过一定的周期进行刷新,这样由于每个用户的开机时间/APP 启动时间不同,可避免同时刷新数据或同时产生大量请求。
必须项

中国地区数据合规要求

法律法规要求:根据中国法律法规要求,在中国境内地区使用天气预报数据时,必须使用中国气象局发布的预报数据。

数据识别与使用

API 返回数据中,LocalSource 字段的 id 值为 7 时,代表该数据来源于中国气象局(Huafeng)。此类数据包含特定的编码字段,需要通过编码表进行解析。

数据结构示例
"LocalSource": {
  "id": 7,
  "Name": "Huafeng",
  "WeatherCode": "01",
  "WindLevelCode": "3",
  "WindDirectionCode": "3"
}

编码字段说明

快速参考

所有编码表已整理在「实用资料」模块中,包括完整的天气现象编码、风向编码、风力等级编码等。请前往实用资料查看详细的编码对照表和使用说明。

必须项

遵守华风爱科对 API 调用的指南和要求

遵守华风爱科对 API 调用的指南和要求。请注意,华风爱科提供的新的指南和要求,也需及时更新满足。

必须项

对 Minutecast 接口的 HTTP 400 错误进行容错处理

请特别注意:某些区域某些时次没有雷达数据时,Minutecast 接口会返回 HTTP 400 错误,请务必对这种情况做容错处理。

建议项

利用 Response Header 中的数据有效期进行刷新

  • 利用 Response Header 中的数据有效期限进行新的数据刷新请求。
HTTP Headers 示例
Response Headers
Cache-Control: public
Content-Encoding: gzip
Content-Type: application/json; charset=utf-8
Date: Wed, 29 Aug 2012 14:55:33 GMT
Expires: Thu, 30 Aug 2012 14:56:34 GMT
Server: Microsoft-IIS/7.5
Server: Microsoft-IIS/7.0
Transfer-Encoding: chunked
Vary: Accept-Encoding
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
  • 在这个例子中,Expires: Thu, 30 Aug 2012 14:56:34 GMT 意味着数据在此时间前均有效,建议在此时间前不再重新请求。
建议项

MinuteCast™ 缓存

  • 在中国地区的 MinuteCast 正在建设中,现阶段 API 还无法提供中国某些区域内的分钟级降水。如果当前位置不支持此服务,系统将会返回 HTTP 400 错误;
  • 为减少流量使用以及增长您设备的电池续航,我们建议开发时设置缓存 1 小时的 MinuteCast™ HTTP 400 反馈以避免后续重复请求与返回 HTTP 400 错误。
注意项

夏令时间影响

如果您使用了定位 API 接口返回结果中的 GMTOffset 来计算当地时间,请务必检查 NextOffsetChange,即下一次的 Offset 变化时间。

这样您可预知 Offset 将在何时变化,并能够在变化后及时的获取最新的 Offset 来准确的显示当地时间。