天机API概览

本文档为天机API接口调用试用规范，为第三方开发和测试提供参考。如本文档有遗漏或者不能满足您的需求，请联系运营人员进行反馈。

接口设计

本文档定义了第三方开发和测试提供API调用方式 ，目前支持大气要素: 100米风速和风向、10米风速和风向、2米温度、降雨量、2米湿度、辐照度、总云量、低云量等相关单点数据查询。

资源权限

本结构根据平台用户名和密码做权限认定，第三方平台需获取到授权该平台的APIKey，才可正常调用API。 您可通过以下任一途径注册/登录并提交API服务申请：

1. 直接访问申请页面完成操作：https://www.tjweather.com/Apply
2. 进入数据服务页面，点击【API 服务】申请：https://www.tjweather.com/Service

首次申请权益：默认开通地面6要素数据接口，包含2 米气温（t2m）、10 米风速（ws10m）、10 米风向（wd10m）、气压（slp）、相对湿度（rh2m）、降水（tp）

使用规则：非商业用途用户首次可免费试用2个月，若需新增数据要素、延长试用期限或开展商业合作，可通过平台首页【客服咨询】联系我们。

支持协议

接口均使用https协议进行访问，确保数据加密传输。

认证机制

采用基于key的用户认证机制，用户调用接口前需要先获取APIKey，在调用其他所有接口时需要携带APIKey参数。

返回结果

这里的返回结果专指在HTTP响应的状态码（Status Code）为200时的响应信息。

所有返回结果默认均使用JSON格式，接口中定义的对象都将转换为JSON格式，字符编码格式为UTF-8。HTTP响应头设置Content-Type:application/json;charset=UTF-8。 对于文件下载以及流请求，返回的是数据流

标准正确格式为：{"code":200,"message":"成功","data":Json对象或列表}；

标准错误格式为：{"code":非200,"message":"xxx","data":""}；

其中code为错误码，message为错误信息，data为返回值，格式为JSON对象、列表或字符串。

错误处理

首先需要判断HTTP响应的状态码（Status Code），如果为404、500等状态，则按照浏览器等常用HTTP客户端的惯例处理。

返回状态码为200时，表示服务器处理正常，此时再判断返回结果，根据具体接口的返回值中的错误码code进行处理，具体请参考各接口的错误码说明。

如果返回结果与上节描述的格式不一致，即非JSON格式，应以错误处理。如果返回结果的对象中缺少某个属性，则应以该属性的值为空串处理。