天气预报-获取全国天气预警数据API接口教程-阿里云开发者社区

一、接口概述

该接口由接口盒子提供，是一个专门用于获取全国当前所有地区气象局发布的天气预警数据的免费API接口。通过该接口，开发者可以实时获取全国各地发布的各类天气预警信息，包括暴雨、大风、雷电、高温、大雾等多种预警类型，以及对应的预警等级、生效时间等详细信息。

核心功能：

获取全国范围内当前生效的天气预警数据
支持分页查询，每页最多返回20条预警信息
提供完整的行政区划信息和预警详情
支持GET和POST两种请求方式

二、接口基本信息

请求地址：

复制

https://cn.apihz.cn/api/dingzhi/tqyjall.php

请求方式：

POST 或 GET

请求参数：

参数名称	参数	必填	说明
用户ID	id	是	用户中心的数字ID，例如：id=10000000
用户KEY	key	是	用户中心通讯秘钥，例如：key=15he5h15ty854j5sr152hs2
页码	page	否	默认第1页，最大不超过1000页，每页最多返回20条数据集，例如：page=1

三、返回参数详解

接口返回JSON格式数据，主要包含以下字段：

基础信息字段：

code：状态码（200表示成功，400表示错误）
msg：信息提示
page：当前页码

行政区划信息：

sheng：省级行政区（不带后缀"省"）
shi：市级行政区（不带后缀"市"）
name：地点名称
sheng2：省级行政区（带后缀"省"）
shi2：市级行政区（带后缀"市"）
qu2：区县级行政区或以下
code5：区划代码

预警数据集（alarm数组）：

每个预警信息包含以下字段：

alarm.id：预警编号，唯一标识符（用于查询详细预警信息）
alarm.title：预警标题
alarm.signaltype：预警天气类别（如：暴雨、大风、雷电等）
alarm.signallevel：预警等级（如：红色、橙色、黄色、蓝色）
alarm.effective：预警生效时间（格式：YYYY/MM/DD HH:MM）
alarm.eventType：事件类型代码
alarm.severity：预警等级（英文）
alarm.type：预警类型代码

四、调用示例

PHP调用示例

php

复制

<?php
/**
 * 获取全国天气预警数据 - PHP示例
 */
class WeatherWarningAPI {
    private $apiUrl = 'https://cn.apihz.cn/api/dingzhi/tqyjall.php';
    private $userId = '你的用户ID';  // 替换为实际用户ID
    private $userKey = '你的用户KEY'; // 替换为实际用户KEY
    
    /**
     * 使用GET方式获取天气预警数据
     * @param int $page 页码，默认为1
     * @return array 解析后的预警数据
     */
    public function getWeatherWarningsByGet($page = 1) {
        // 构建请求URL
        $url = $this->apiUrl . '?id=' . $this->userId . '&key=' . $this->userKey . '&page=' . $page;
        
        // 发送GET请求
        $response = file_get_contents($url);
        
        if ($response === false) {
            return ['error' => '请求失败，请检查网络连接'];
        }
        
        // 解析JSON响应
        $data = json_decode($response, true);
        
        // 检查返回状态
        if ($data['code'] != 200) {
            return ['error' => '接口返回错误: ' . $data['msg']];
        }
        
        return $data;
    }
    
    /**
     * 使用POST方式获取天气预警数据
     * @param int $page 页码，默认为1
     * @return array 解析后的预警数据
     */
    public function getWeatherWarningsByPost($page = 1) {
        // 准备POST数据
        $postData = http_build_query([
            'id' => $this->userId,
            'key' => $this->userKey,
            'page' => $page
        ]);
        
        // 配置请求选项
        $options = [
            'http' => [
                'method' => 'POST',
                'header' => 'Content-type: application/x-www-form-urlencoded',
                'content' => $postData
            ]
        ];
        
        // 创建上下文并发送请求
        $context = stream_context_create($options);
        $response = file_get_contents($this->apiUrl, false, $context);
        
        if ($response === false) {
            return ['error' => '请求失败，请检查网络连接'];
        }
        
        // 解析JSON响应
        $data = json_decode($response, true);
        
        // 检查返回状态
        if ($data['code'] != 200) {
            return ['error' => '接口返回错误: ' . $data['msg']];
        }
        
        return $data;
    }
    
    /**
     * 使用cURL方式获取天气预警数据（推荐）
     * @param int $page 页码，默认为1
     * @return array 解析后的预警数据
     */
    public function getWeatherWarningsByCurl($page = 1) {
        // 构建请求URL
        $url = $this->apiUrl . '?id=' . $this->userId . '&key=' . $this->userKey . '&page=' . $page;
        
        // 初始化cURL
        $ch = curl_init();
        
        // 设置cURL选项
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // 生产环境建议设为true
        curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); // 生产环境建议设为2
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        
        // 执行请求
        $response = curl_exec($ch);
        
        // 检查错误
        if (curl_errno($ch)) {
            $error = curl_error($ch);
            curl_close($ch);
            return ['error' => 'cURL请求失败: ' . $error];
        }
        
        curl_close($ch);
        
        // 解析JSON响应
        $data = json_decode($response, true);
        
        // 检查返回状态
        if ($data['code'] != 200) {
            return ['error' => '接口返回错误: ' . $data['msg']];
        }
        
        return $data;
    }
    
    /**
     * 格式化显示预警信息
     * @param array $apiData API返回的数据
     */
    public function displayWarnings($apiData) {
        if (isset($apiData['error'])) {
            echo "错误: " . $apiData['error'] . "\n";
            return;
        }
        
        echo "=== 全国天气预警数据（第" . $apiData['page'] . "页） ===\n\n";
        
        foreach ($apiData['data'] as $location) {
            echo "地区: " . $location['sheng2'] . $location['shi2'] . $location['qu2'] . "\n";
            echo "区划代码: " . $location['code5'] . "\n";
            
            if (!empty($location['alarm'])) {
                echo "预警信息:\n";
                foreach ($location['alarm'] as $index => $warning) {
                    echo "  " . ($index + 1) . ". " . $warning['title'] . "\n";
                    echo "     类型: " . $warning['signaltype'] . "\n";
                    echo "     等级: " . $warning['signallevel'] . " (" . $warning['severity'] . ")\n";
                    echo "     生效时间: " . $warning['effective'] . "\n";
                    echo "     预警ID: " . $warning['id'] . "\n";
                }
            } else {
                echo "当前无预警信息\n";
            }
            echo str_repeat("-", 50) . "\n";
        }
        
        echo "总计: " . count($apiData['data']) . "个地区有预警信息\n";
    }
}
// 使用示例
$api = new WeatherWarningAPI();
// 方法1：使用GET方式获取第1页数据
$data = $api->getWeatherWarningsByGet(1);
$api->displayWarnings($data);
// 方法2：使用cURL方式获取数据（推荐）
// $data = $api->getWeatherWarningsByCurl(1);
// $api->displayWarnings($data);
// 方法3：使用POST方式获取数据
// $data = $api->getWeatherWarningsByPost(1);
// $api->displayWarnings($data);
?>

Python调用示例

python

下载

复制

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
获取全国天气预警数据 - Python示例
"""
import requests
import json
from typing import Dict, List, Optional, Any
class WeatherWarningAPI:
    """天气预警API客户端类"""
    
    def __init__(self, user_id: str, user_key: str):
        """
        初始化API客户端
        
        Args:
            user_id: 用户ID
            user_key: 用户KEY
        """
        self.api_url = "https://cn.apihz.cn/api/dingzhi/tqyjall.php"
        self.user_id = user_id
        self.user_key = user_key
        
    def get_weather_warnings(self, page: int = 1, method: str = "GET") -> Dict[str, Any]:
        """
        获取天气预警数据
        
        Args:
            page: 页码，默认为1
            method: 请求方法，GET或POST
            
        Returns:
            包含预警数据的字典
        """
        # 准备请求参数
        params = {
            "id": self.user_id,
            "key": self.user_key,
            "page": page
        }
        
        try:
            if method.upper() == "GET":
                # GET请求
                response = requests.get(
                    self.api_url,
                    params=params,
                    timeout=30,
                    verify=False  # 生产环境建议设为True
                )
            elif method.upper() == "POST":
                # POST请求
                response = requests.post(
                    self.api_url,
                    data=params,
                    timeout=30,
                    verify=False  # 生产环境建议设为True
                )
            else:
                return {"error": "不支持的请求方法，请使用GET或POST"}
            
            # 检查HTTP状态码
            response.raise_for_status()
            
            # 解析JSON响应
            data = response.json()
            
            # 检查API返回状态
            if data.get("code") != 200:
                return {
                    "error": f"接口返回错误: {data.get('msg', '未知错误')}",
                    "code": data.get("code")
                }
            
            return data
            
        except requests.exceptions.Timeout:
            return {"error": "请求超时，请检查网络连接"}
        except requests.exceptions.ConnectionError:
            return {"error": "网络连接错误"}
        except requests.exceptions.HTTPError as e:
            return {"error": f"HTTP错误: {str(e)}"}
        except json.JSONDecodeError:
            return {"error": "响应数据解析失败"}
        except Exception as e:
            return {"error": f"未知错误: {str(e)}"}
    
    def get_warnings_with_retry(self, page: int = 1, max_retries: int = 3) -> Dict[str, Any]:
        """
        带重试机制的获取预警数据
        
        Args:
            page: 页码
            max_retries: 最大重试次数
            
        Returns:
            预警数据或错误信息
        """
        for attempt in range(max_retries):
            result = self.get_weather_warnings(page)
            if "error" not in result:
                return result
            print(f"第{attempt + 1}次尝试失败: {result['error']}")
        
        return {"error": f"经过{max_retries}次尝试后仍然失败"}
    
    def display_warnings(self, data: Dict[str, Any]) -> None:
        """
        格式化显示预警信息
        
        Args:
            data: API返回的数据
        """
        if "error" in data:
            print(f"错误: {data['error']}")
            return
        
        print(f"=== 全国天气预警数据（第{data.get('page', 1)}页） ===\n")
        
        locations = data.get("data", [])
        if not locations:
            print("当前无预警信息")
            return
        
        warning_count = 0
        for location in locations:
            province = location.get("sheng2", "")
            city = location.get("shi2", "")
            district = location.get("qu2", "")
            code = location.get("code5", "")
            
            print(f"地区: {province}{city}{district}")
            print(f"区划代码: {code}")
            
            alarms = location.get("alarm", [])
            if alarms:
                print("预警信息:")
                for i, warning in enumerate(alarms, 1):
                    title = warning.get("title", "")
                    signal_type = warning.get("signaltype", "")
                    signal_level = warning.get("signallevel", "")
                    severity = warning.get("severity", "")
                    effective_time = warning.get("effective", "")
                    warning_id = warning.get("id", "")
                    
                    print(f"  {i}. {title}")
                    print(f"     类型: {signal_type}")
                    print(f"     等级: {signal_level} ({severity})")
                    print(f"     生效时间: {effective_time}")
                    print(f"     预警ID: {warning_id}")
                    
                    warning_count += 1
            else:
                print("当前无预警信息")
            
            print("-" * 50)
        
        print(f"总计: {len(locations)}个地区有预警信息，共{warning_count}条预警")
    
    def save_to_file(self, data: Dict[str, Any], filename: str = "weather_warnings.json") -> bool:
        """
        将预警数据保存到文件
        
        Args:
            data: 预警数据
            filename: 文件名
            
        Returns:
            保存是否成功
        """
        try:
            with open(filename, 'w', encoding='utf-8') as f:
                json.dump(data, f, ensure_ascii=False, indent=2)
            print(f"数据已保存到: {filename}")
            return True
        except Exception as e:
            print(f"保存文件失败: {str(e)}")
            return False
    
    def get_warnings_by_province(self, province: str, page: int = 1) -> List[Dict[str, Any]]:
        """
        按省份筛选预警信息
        
        Args:
            province: 省份名称（不带"省"后缀）
            page: 页码
            
        Returns:
            该省份的预警信息列表
        """
        data = self.get_weather_warnings(page)
        if "error" in data:
            return []
        
        province_warnings = []
        for location in data.get("data", []):
            if location.get("sheng") == province:
                province_warnings.append(location)
        
        return province_warnings
def main():
    """主函数示例"""
    # 配置你的用户ID和KEY（请替换为实际值）
    USER_ID = "你的用户ID"
    USER_KEY = "你的用户KEY"
    
    # 创建API客户端实例
    api = WeatherWarningAPI(USER_ID, USER_KEY)
    
    print("开始获取天气预警数据...\n")
    
    # 示例1：获取第1页预警数据（GET方式）
    print("示例1：使用GET方式获取第1页数据")
    print("=" * 60)
    data = api.get_weather_warnings(page=1, method="GET")
    api.display_warnings(data)
    
    # 示例2：保存数据到文件
    if "error" not in data:
        api.save_to_file(data, "weather_warnings_page1.json")
    
    print("\n" + "=" * 60 + "\n")
    
    # 示例3：按省份筛选预警信息
    print("示例2：筛选江西省的预警信息")
    print("=" * 60)
    jiangxi_warnings = api.get_warnings_by_province("江西", page=1)
    
    if jiangxi_warnings:
        print(f"江西省共有{len(jiangxi_warnings)}个地区发布预警：")
        for location in jiangxi_warnings:
            province = location.get("sheng2", "")
            city = location.get("shi2", "")
            district = location.get("qu2", "")
            alarm_count = len(location.get("alarm", []))
            print(f"  - {province}{city}{district}: {alarm_count}条预警")
    else:
        print("江西省当前无预警信息或获取失败")
    
    print("\n" + "=" * 60 + "\n")
    
    # 示例4：使用带重试的获取方式
    print("示例3：使用带重试机制获取数据（第2页）")
    print("=" * 60)
    retry_data = api.get_warnings_with_retry(page=2, max_retries=2)
    if "error" not in retry_data:
        print(f"第2页获取成功，共有{len(retry_data.get('data', []))}个地区数据")
    else:
        print(f"获取失败: {retry_data['error']}")
if __name__ == "__main__":
    # 使用示例
    main()
    
    # 快速使用示例
    """
    # 简单使用
    api = WeatherWarningAPI("你的用户ID", "你的用户KEY")
    
    # 获取数据
    data = api.get_weather_warnings(page=1)
    
    # 显示结果
    if "error" not in data:
        api.display_warnings(data)
    else:
        print(f"错误: {data['error']}")
    """

五、返回数据示例解析

从接口文档提供的示例数据可以看出，返回的数据结构清晰，包含了丰富的预警信息：

json

复制

{
  "code": 200,
  "page": 1,
  "data": [
    {
      "sheng": "江西",
      "shi": "崇义",
      "name": "崇义",
      "sheng2": "江西省",
      "shi2": "赣州市",
      "qu2": "崇义",
      "code5": "360725",
      "alarm": [
        {
          "id": "36072541600000_20260412064652",
          "title": "崇义县气象台2026年04月12日06时43分发布暴雨橙色预警信号。",
          "signaltype": "暴雨",
          "signallevel": "橙色",
          "effective": "2026/04/12 06:43",
          "eventType": "11B03",
          "severity": "ORANGE",
          "type": "p0002002"
        }
      ]
    }
  ]
}

数据结构特点：

分层结构：data数组包含多个地区，每个地区包含多个预警
完整行政区划：提供省、市、区县三级信息，包含带后缀和不带后缀两种格式
详细预警信息：每个预警包含标题、类型、等级、生效时间等完整信息
唯一标识：每个预警都有唯一的id，可用于查询详细内容

六、使用注意事项

授权要求：该接口需要购买授权后才能使用，公共ID和KEY有调用频次限制
调用频率：使用自己的ID和KEY可以独享调用频次，每日调用无上限
数据更新：预警数据实时更新，建议根据实际需求设置合理的调用间隔
错误处理：务必检查返回的code字段，200表示成功，400表示错误
分页查询：支持分页查询，每页最多20条数据，最大1000页
详细查询：可以通过预警id调用详细预警查询接口获取更详细的信息

七、应用场景

气象预警系统：集成到气象监测预警平台
应急管理系统：为政府应急管理部门提供数据支持
出行服务应用：为出行App提供实时天气预警信息
农业气象服务：为农业生产提供灾害性天气预警
智慧城市：作为城市安全预警系统的一部分
新闻媒体：为气象新闻报道提供数据来源

八、技术要点总结

接口稳定性：采用标准的HTTP协议，支持GET和POST两种方式
数据完整性：提供完整的行政区划和预警信息
使用便捷性：参数简单，返回数据格式规范
扩展性：支持分页查询，适合大数据量场景
安全性：需要授权验证，保障数据安全

九、常见问题解答

Q1: 如何获取用户ID和KEY？

A: 需要注册接口盒子平台账号，并在后台购买该接口的授权。

Q2: 调用频率有限制吗？

A: 使用公共ID和KEY有频次限制，使用自己的授权可以独享调用频次。

Q3: 数据更新频率是多少？

A: 数据实时更新，与气象局发布预警的时间基本同步。

Q4: 可以获取历史预警数据吗？

A: 该接口只提供当前生效的预警数据，历史数据需要其他接口支持。

Q5: 如何根据预警id查询详细内容？

A: 可以使用"天气预报-气象局-天气预警详细内容查询"接口，传入预警id即可。

十、总结

这个天气预警API接口为开发者提供了一个便捷、可靠的全国天气预警数据获取渠道。通过简单的API调用，就可以获取到全国各地气象局发布的实时预警信息，包括暴雨、大风、雷电、高温等多种预警类型。接口设计合理，数据格式规范，适合集成到各种气象服务、应急管理、出行服务等应用中。

无论是PHP还是Python开发者，都可以通过本文提供的示例代码快速集成该接口到自己的项目中。建议在实际使用中注意错误处理和调用频率控制，确保系统的稳定性和数据的准确性。

天气预报-获取全国天气预警数据API接口教程

一、接口概述

二、接口基本信息

三、返回参数详解

四、调用示例

PHP调用示例

Python调用示例

五、返回数据示例解析

六、使用注意事项

七、应用场景

八、技术要点总结

九、常见问题解答

十、总结

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

天气预报-获取全国天气预警数据API接口教程

一、接口概述

二、接口基本信息

三、返回参数详解

四、调用示例

PHP调用示例

Python调用示例

五、返回数据示例解析

六、使用注意事项

七、应用场景

八、技术要点总结

九、常见问题解答

十、总结

热门文章

最新文章

相关电子书