心知天气 - 天气数据API文档

### 心知天气 - 天气数据API文档 #### API密钥(key)及用户ID(uid) **API密钥**：`rjqbehvosvraxybb` API密钥（key）是一个用于验证API请求合法性的唯一字符串，它通过API请求中的key参数传入。 **用户ID**：`U306FCE4E5` 用户ID是在注册心知会员时获得的一个10位字符串，例如`U123456789`。用户ID在签名验证方式中使用。 #### 使用心知服务的说明 对于**免费用户**来说，在使用心知天气数据时需要在数据展示页面注明数据来源为心知天气；而对于**付费用户**而言，则可以根据自身需求选择是否注明数据来源。 #### 支持的城市和地区 心知天气支持全国2567个、全球24,373个城市和地点。这一覆盖范围涵盖了几乎全球各地，使得开发者和企业能够根据实际需求灵活获取所需地区的天气信息。此外，心知天气还会持续增加支持的城市数量，以实现更全面的服务覆盖。 - **城市列表下载**：可以通过链接下载全球支持城市的列表。 - **全屏地图查看**：可以访问链接查看心知天气支持的所有城市位置的全屏地图。 #### 如何使用签名验证方式 为了保障API使用的安全性，除了基本的API密钥验证之外，心知天气API还提供了更安全的**签名验证方式**： 1. **构造验证参数字符串**：将请求参数按照参数名的字典升序排列后，把所有参数`param=value`用`&`连接起来。目前支持的参数包括：UNIX时间戳(ts)、签名失效时间(ttl，默认为1800秒，即30分钟，可选)以及用户ID(uid)。 例如：`ts=1443079775&ttl=30&uid=U123456789` 2. **使用HMAC-SHA1加密**：使用API密钥（key）对第1步生成的参数字符串进行HMAC-SHA1加密。大部分编程语言都会内置加密函数或者提供相应的扩展库支持，例如Node.js中的`crypto`模块。 例如，在Node.js中可以使用如下代码片段进行加密： ```javascript const crypto = require('crypto'); const key = "secret"; const data = "ts=1443079775&ttl=30&uid=U123456789"; const hmac = crypto.createHmac('sha1', key); const hash = hmac.update(data).digest('base64'); ``` 3. **生成签名(sig)**：将第2步生成的加密结果用base64编码，并做URL编码(urlencode)，得到最终的签名(sig)。 例如：假设key为`secret`，则基于上述参数示例，加密后得到的结果为`dTYeoN8WdOfW4PiwgEdLa0gWFzo=`，完成URL编码后得到的签名sig为`dTYeoN8WdOfW4PiwgEdLa0gWFzo%3d`。 4. **附加签名发送请求**：将签名sig附加在构造好的参数字符串之后，作为请求的一部分发送。 例如：`ts=1443079775&ttl=30&uid=U123456789&sig=dTYeoN8WdOfW4PiwgEdLa0gWFzo%3d` **注意事项**： - 签名失效时间参数ttl是可选的。如果不设置，签名有效期默认为1800秒（30分钟）。较短的有效期可以提高安全性。 - 请求中的其他参数，如location、language等，不参与签名过程。 #### JSONP方式调用 为了方便网页直接调用API接口，心知天气API支持JSONP方式调用，但需要绑定域名并使用签名验证方式。具体方法如下： 1. 在请求中使用`callback`参数指定回调函数的名字。 2. 使用签名验证方式构造请求。 3. 在网页中通过`<script>`标签的方式调用API。 **示例**： ```html <script type="text/javascript" src="https://api.seniverse.com/v3/weather/now.json?location=beijing&ts=1443079775&ttl=30&uid=[your_uid]&sig=[your_signature]&callback=showWeather"></script> ``` **返回结果**： ```javascript showWeather({ "results": [{ "location": { "id": "WX4FBXXFKE4F", "name": "北京" }, ... }] }); ``` #### 天气数据单位的说明 在实际应用中，了解心知天气提供的数据单位非常关键，这有助于正确解读和展示天气信息。具体的数据单位将在官方文档中有详细的说明，确保开发者能够准确无误地使用这些数据。 心知天气API提供了丰富的功能和服务，不仅支持广泛的城市和地区，还通过多种验证方式确保了数据的安全性和准确性。无论是对于个人开发者还是企业级用户来说，都能够从中受益匪浅。