本文全面介绍由接口盒子免费API提供的全球天气预报API，支持通过经纬度坐标获取任意地区未来5天的详细天气预报数据。
一、接口核心功能
- 全球覆盖：支持全球任意经纬度坐标点的天气预报
- 高精度预报：提供每3小时为间隔的精细化预报（5天共40组数据）
- 多维度数据：包含天气状况、温度、气压、湿度、风速等12项气象要素
- 免费使用：个人开发者可直接调用（需注册获取专属KEY）
二、接口基本信息
| 项目 | 说明 |
|---|---|
| 请求地址 | https://cn.apihz.cn/api/tianqi/tqybjw5.php |
| 请求方式 | GET/POST |
| 数据格式 | JSON |
| 响应时间 | 平均200-500ms |
三、请求参数说明
| 参数名 | 必填 | 示例值 | 说明 |
|---|---|---|---|
| id | 是 | 10000000 | 用户中心注册的数字ID |
| key | 是 | 15he5h15ty854j5sr152hs2 | 用户中心通讯秘钥 |
| lat | 是 | 40.05702706489032 | 纬度坐标（十进制） |
| lon | 是 | 116.30787799999993 | 经度坐标（十进制） |
📌 重要提示：
示例中的88888888为公共测试KEY，实际使用请注册获取专属KEY
免费版限制：5次/分钟，无日总量限制
四、返回参数详解
json
复制
{"code": 200, // 状态码(200成功,400错误)"cnt": 40, // 数据组数量(5天×8组/天)"name": "Haidian", // 最近城市名称"country": "CN", // 国家代码(ISO标准)"sunrise": 1726523854, // 日出时间戳"sunset": 1726568470, // 日落时间戳"data": [ // 天气预报数据集合{"dt": 1726552800, // 时间戳"time": "2024-09-17 06:00:00", // 本地时间"temp": 300.91, // 开氏温度(K)"temph": 27.76, // 摄氏温度(℃) "pressure": 1006, // 气压(hPa)"humidity": 44, // 湿度(%)"weather": "晴", // 天气现象"clouds": 2, // 云量百分比(%)"speed": 2.67, // 风速(m/s)"deg": 111, // 风向(度)"visibility": 10000 // 能见度(米)},// ...共40组数据...]
}🌡️ 温度说明：
temp：开尔文温度（科学计算常用）temph：摄氏温度（日常使用）
转换公式：℃ = K - 273.15
五、调用示例代码
PHP调用示例
php
复制
<?php
// 配置参数
$apiUrl = "https://cn.apihz.cn/api/tianqi/tqybjw5.php";
$params = ['id' => '10000000', // 替换为您的ID'key' => '您的专属KEY', // 替换为您的KEY'lat' => '40.057027', // 纬度'lon' => '116.307878' // 经度
];// 构造请求URL
$requestUrl = $apiUrl . '?' . http_build_query($params);// 发起GET请求
$response = file_get_contents($requestUrl);// 处理响应
if ($response !== false) {$weatherData = json_decode($response, true);if ($weatherData['code'] == 200) {echo "城市: " . $weatherData['name'] . "\n";echo "今日天气: " . $weatherData['data'][0]['weather'];echo "温度: " . round($weatherData['data'][0]['temph'], 1) . "℃";} else {echo "错误: " . $weatherData['msg'];}
} else {echo "API请求失败";
}
?>Python调用示例
python
运行
复制
import requests# 配置参数
params = {"id": "10000000", # 替换为您的ID"key": "您的专属KEY", # 替换为您的KEY"lat": "40.057027", # 纬度"lon": "116.307878" # 经度
}try:# 发送GET请求response = requests.get("https://cn.apihz.cn/api/tianqi/tqybjw5.php",params=params)weather_data = response.json()if weather_data['code'] == 200:# 提取首条数据first_report = weather_data['data'][0]print(f"城市: {weather_data['name']}")print(f"时间: {first_report['time']}")print(f"天气: {first_report['weather']}")print(f"温度: {round(first_report['temph'], 1)}℃")print(f"风速: {first_report['speed']}m/s")else:print(f"错误: {weather_data['msg']}")except Exception as e:print(f"请求异常: {str(e)}")六、使用注意事项
- 坐标获取：需先通过地理编码服务获取经纬度
- 时间说明：返回时间均为当地标准时间
- 单位规范：
- 温度：摄氏度(℃)/开尔文(K)双轨提供
- 气压：百帕(hPa)
- 风速：米/秒(m/s)
- 错误处理：常见错误码：
400：参数错误或KEY验证失败500：服务器内部错误
七、应用场景
- 气象数据可视化平台
- 出行类APP的天气模块
- 物联网设备环境监测
- 农业种植气候监控
- 户外活动安全预警系统
