ICS 07.060 CCS A 47 中华人民共和国国家标准 GB/T 42877—2023 气象数据服务接口规范 Service interface specification for meteorological data 2023-12-01实施 2023-08-06发布 国家市场监督管理总局 发布 国家标准化管理委员会 GB/T42877—2023 目 次 前言 范围 1 2 规范性引用文件 术语和定义 接口组成 4 5 接口名称 接口参数 6 1 返回码 8 返回数据结构 证实方法 附录A（资料性） 气象数据服务接口示例 附录B（规范性） 接口参数定义 附录C（规范性） 返回码取值含义 附录D（规范性） 返回数据结构 参考文献 31 GB/T 42877—2023 前言 本文件按照GB/T1.1—2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》的规定 起草。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任 本文件由中国气象局提出。 本文件由全国气象基本信息标准化技术委员会（SAC/TC346）归口。 本文件起草单位：国家气象信息中心、广东省气象探测数据中心、四川省气象探测数据中心、陕西气 象信息中心、内蒙古自治区气象信息中心、华云信息技术工程有限公司。 本文件主要起草人：何文春、高峰、徐拥军、王琦、倪学磊、孙周军、宋智、何林、温建伟、郑波、刘媛媛。 GB/T 42877—2023 气象数据服务接口规范 1范围 本文件规定了气象数据服务接口的组成、名称、参数、返回码与返回数据结构，并描述了对应的证实 方法。 本文件适用于气象数据服务接口的设计开发、调取应用和气象数据的提供、使用： 2规范性引用文件 2 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文 件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于 本文件。 GB/T22602007 中华人民共和国行政区划代码 GB/T2659一2000世界各国和地区名称代码 GB/T40153—2021 气象资料分类与编码 QX/T37—2020 气象台站历史沿革数据文件格式 QX/T 202—2013 表格驱动码气象数据传输文件规范 QX/T327—2016 气象卫星数据分类与编码规范 QX/T 378—2017 公共气象服务产品文件命名规范 3 术语和定义 下列术语和定义适用于本文件。 3.1 气象数据meteorologicaldata 使用各种观测、探测手段获取的地球表面和地球大气的状态、现象及其变化过程的记录，以及以此 为基础，通过各种技术方法进行加工处理生成的各类衍生和加工产品。 ［来源：GB/T40153—2021，3.1，有修改］ 3.2 [服务】接口 service interface 信息系统为开放特定业务功能而发布的可供其他系统调用的应用编程函数。 3.3 数据类别 Jdata category 具有共同属性（或特征）的数据的集合。 ［来源：GB/T38667—2020，3.9，有修改］ 3.4 返回码returncode 服务接口调用后返回的、用以标识调用成功与否和错误原因等信息的状态码。 注：一般用一个数字表示。 1 GB/T42877—2023 3.5 返回数据结构structureforreturneddata 服务接口调用后返回的内存对象的数据组织方式。 3.6 序列化 serialization 将计算机内存对象转换为可保存或传输的数据格式的过程。 注：保存或传输的数据格式一般有XML、JSON、JSONP、TEXT、HTML等。 4接口组成 4.1 接口应由4部分组成： a) 接口名称：表达数据访问的具体功能； b) 接口参数：表达数据访问的输人条件； c) 返回码：表达数据访问的调用状态； d）返回数据结构：表达返回数据的内存对象结构。 4.2 一个接口可有一个或多个参数，每个参数应明确为必选或可选。接口示例见附录A，接口参数定 义、返回码取值和返回数据结构应分别符合附录B、附录C和附录D的规定 5 接口名称 数据内容不应为空，主要条件可为空。 5.2接口名称宜采用小驼峰命名法1，命名格式为：（接口功能）（数据类别）（数据内容）（主要条件）。各 组成部分的取值应符合表1的规则。 表1接口名称各组成部分的取值规则 组成部分 代码 含义 备注 get 直接获取气象数据或资料的方法 接口功能的范围为提供数据，不包含回 写数据。 接口功能 统计气象数据或资料的方法，包括：累计、极 接口功能及其代码取值宜根据需要 stat 值、平均、计数等统计方法 扩展 Surf 地面气象资料 Upar 高空气象资料 Ocen 海洋气象资料 数据类别 Radi 气象辐射资料 符合GB/T40153—2021第5章的要求 Agme 农业气象和生态气象资料 Nafp 数值预报产品 Cawn 大气成分资料 1）小驼峰命名法：软件编程中对编程对象的一种命名规则，名称由一个或多个单词连结而成，单词间不设分隔符， 第一个单词的所有字母均为小写，从第二个单词开始之后的每个单词的首字母大写、其余字母均小写。 2 GB/T . 备注 40153—2021第5章的要求 空间天气资料 其他资料 要素 适用于站点类、格点类数据 数据内容 文件 适用于信息类数据（文件形 多个直接连出 多个条件以 参数名称应 则应符合6 数 参数宜分为6 据范围，分别按照数据的代码、要素、时间 三要维度定义： 数。参数类别及其描述的输人条件应 参数类别及其描述的输， 参数描述的辅 居代码（单个） 十要素）范围。如：要素列表 时间范 可段 空间范 范围 风编号。分为“数值预报产品参数”“天气雷达资料参数” 特殊属 品参数”等 其他 6.2接口 直格式、赋值示 名称宜采用 小驼峰命名 6.3接口# 口参数宜根据 展。 3 GB/T 42877 返回码 7.1 返回码分为成功类、 类的返回码取值为0。失败类的返回码取值为负数，取值规则 001开始。 3 错误类吴 错误类别代码 错误类别名称 没有数据 0 1 用户验证失败 2 口与数据不匹配 3 接口参数错误 没有访问权限 单次请求范围过大 服务器连接错误 数据库操作错误 数据文件错误 服务器处理错误 10 其他错误 7.2 2返回码的取值含义应 义的返回码，宜根据需要按照返回码的取值含义 扩展。 8 返回数据结构 8.1 接口返回数据结构类别分为：站点类、格点类和信息类。返回 数据内容应符合表4的规定。 表4接口返回数据结构类别信 返回数据结 适用数据范围 返回数据内容 类数据。如：地面气象资料、高空气象 海洋气象资料、气象辐射资料、农业气 二维站点数据及其描述信息、接口调用过程 站点类 生态气象资料、大气成分资料、历史气 信息 用资料、气象灾害资料、空间天气资 料等 二维格点场数据及其描述信息、接口调用过程 格点类数据。如：数值预报产品等 信息 文件类数据。如：天气雷达资料、卫星气象 文件信息列表及其描述信息、接口调用过程 资料、数值预报产品、科学试验和考察资料、 信息 气象厂