GBT 42877-2023 气象数据服务接口规范

气象数据服务接口规范Serviceinterfacespecificationformeteorologicaldata2023-08-06发布国家市场监督管理总局国家标准化管理委员会GB/T42877—2023前言 I1范围 2规范性引用文件 3术语和定义 4接口组成 25接口名称 26接口参数 37返回码 48返回数据结构 49证实方法 5附录A(资料性)气象数据服务接口示例 6附录B(规范性)接口参数定义 附录C(规范性)返回码取值含义 附录D(规范性)返回数据结构 参考文献 I本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由中国气象局提出。本文件由全国气象基本信息标准化技术委员会(SAC/TC346)归口。本文件起草单位：国家气象信息中心、广东省气象探测数据中心、四川省气象探测数据中心、陕西气象信息中心、内蒙古自治区气象信息中心、华云信息技术工程有限公司。1气象数据服务接口规范本文件规定了气象数据服务接口的组成、名称、参数、返回码与返回数据结构，并描述了对应的证实方法。本文件适用于气象数据服务接口的设计开发、调取应用和气象数据的提供、使用。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GB/T2260—2007中华人民共和国行政区划代码GB/T2659—2000世界各国和地区名称代码GB/T40153—2021气象资料分类与编码QX/T37—2020气象台站历史沿革数据文件格式QX/T202—2013表格驱动码气象数据传输文件规范QX/T327—2016气象卫星数据分类与编码规范QX/T378—2017公共气象服务产品文件命名规范3术语和定义下列术语和定义适用于本文件。气象数据meteorologicaldata使用各种观测、探测手段获取的地球表面和地球大气的状态、现象及其变化过程的记录，以及以此为基础，通过各种技术方法进行加工处理生成的各类衍生和加工产品。[服务]接口serviceinterface信息系统为开放特定业务功能而发布的可供其他系统调用的应用编程函数。数据类别datacategory具有共同属性(或特征)的数据的集合。服务接口调用后返回的、用以标识调用成功与否和错误原因等信息的状态码。注：一般用一个数字表示。2服务接口调用后返回的内存对象的数据组织方式。将计算机内存对象转换为可保存或传输的数据格式的过程。4接口组成4.1接口应由4部分组成：a)接口名称：表达数据访问的具体功能；b)接口参数：表达数据访问的输入条件；c)返回码：表达数据访问的调用状态；d)返回数据结构：表达返回数据的内存对象结构。4.2一个接口可有一个或多个参数，每个参数应明确为必选或可选。接口示例见附录A,接口参数定义、返回码取值和返回数据结构应分别符合附录B、附录C和附录D的规定。5接口名称5.1接口名称应由4部分组成：接口功能、数据类别、数据内容、主要条件。其中，接口功能、数据类别、数据内容不应为空，主要条件可为空。5.2接口名称宜采用小驼峰命名法¹,命名格式为：{接口功能}{数据类别}{数据内容}{主要条件}。各组成部分的取值应符合表1的规则。表1接口名称各组成部分的取值规则组成部分代码含义备注接口功能直接获取气象数据或资料的方法接口功能的范围为提供数据，不包含回写数据。接口功能及其代码取值宜根据需要扩展值、平均、计数等统计方法数据类别地面气象资料符合GB/T40153—2021第5章的要求高空气象资料海洋气象资料气象辐射资料Agme农业气象和生态气象资料Nafp数值预报产品大气成分资料第一个单词的所有字母均为小写，从第二个单词开始之后的每个单词的首字母大写、其余字母均小写。3表1接口名称各组成部分的取值规则(续)组成部分代码含义备注数据类别历史气候代用资料符合GB/T40153—2021第5章的要求气象灾害资料天气雷达资料卫星气象资料科学试验和考察资料气象服务产品空间天气资料其他资料数据内容要素适用于站点类、格点类数据(要素形式)文件适用于信息类数据(文件形式)要素代码列表数据中所包含的全部或部分要素多个直接连接，不用分隔符主要条件{参数名称主要参数条件多个条件以“And”连接。参数名称应符合附录B的规定，连接规则应符合6.2的规定6接口参数6.1接口参数宜分为6类。其中，5类用于限定数据范围，分别按照数据的代码、要素、时间、空间、特殊属性5个主要维度定义；1类用于定义其他接口参数。参数类别及其描述的输入条件应符合表2的规定。表2参数类别及其描述的输入条件参数类别参数描述的输入条件数据代码类数据代码。如：数据代码(单个)要素范围类数据的要素(含统计要素)范围。如：要素列表时间范围类数据的时间范围。如：时间点、时间段空间范围类数据的空间范围。如：经度和纬度范围特殊属性类数据的其他特殊属性范围。如：台风编号。分为“数值预报产品参数”“天气雷达资料参数”“卫星气象资料参数”“气象服务产品参数”等其他类接口其他参数。如：结果排序字段6.2接口参数定义应由名称、含义、赋值类型、赋值格式、赋值示例、使用说明组成。其中，名称宜采用小驼峰命名法连接。6.3接口参数定义应符合附录B的规定。其他接口参数宜根据需要按照接口参数定义扩展。47.1返回码分为成功类、失败类。成功类的返回码取值为0。失败类的返回码取值为负数，取值规则为-{错误类别代码}{顺序号}。其中，错误类别代码和名称应符合表3的规定，顺序号为3位数字，从001开始。表3错误类别代码和名称错误类别代码错误类别名称0没有数据1用户验证失败2接口与数据不匹配3接口参数错误4没有访问权限5单次请求范围过大6服务器连接错误7数据库操作错误8数据文件错误9服务器处理错误其他错误7.2返回码的取值含义应符合附录C的规定。未定义的返回码，宜根据需要按照返回码的取值含义扩展。8返回数据结构8.1接口返回数据结构类别分为：站点类、格点类和信息类。返回数据结构类别、适用数据范围、返回数据内容应符合表4的规定。表4接口返回数据结构类别信息返回数据结构类别适用数据范围返回数据内容站点类站点类数据。如：地面气象资料、高空气象资料、海洋气象资料、气象辐射资料、农业气象和生态气象资料、大气成分资料、历史气候代用资料、气象灾害资料、空间天气资料等二维站点数据及其描述信息、接口调用过程信息格点类格点类数据。如：数值预报产品等二维格点场数据及其描述信息、接口调用过程信息信息类资料、数值预报产品、科学试验和考察资料、气象服务产品、其他资料等文件信息列表及其描述信息、接口调用过程信息58.2接口返回数据结构描述应符合D.1的规定，站点类、格点类、信息类应分别按D.2、D.3和D.4的规9证实方法9.1接口发布者应提供接口说明文档、测试方案说明文档。9.2审核接口说明文档应包括但不限于接口设计和服务功能、接口发布网站与在线支持、接口应用开发与实践等内容。9.3审核测试方案说明文档应包括但不限于测试环境、测试准备、功能测试用例、非功能测试用例、测试流程等内容。9.4模拟接口使用者应通过接口开发验证程序测试接口运行情况。验证程序应按照接口说明文档的接口名称和参数输入，调用后的返回码和返回数据结构与接口说明文档、测试方案说明文档应一致。6(资料性)气象数据服务接口示例A.1站点类数据服务接口示例表A.1指定时间的地面气象资料检索接口示例接口名称getSurfEleByTime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选数据代码字符串标识_HOR表示：中国地面逐小时数据必选要素代码字符串多个以逗号(,)分隔表示：检索温度、降水数据必选时间字符串YYYYMMDDHH-MISS表示：2008年1月1日00点00分00秒必选表A.2给出了指定时间、垂直探测意义、经纬度范围的高空气象资料检索接口示例。表A.2指定时间、垂直探测意义、经纬度范围的高空气象资料检索接口示例接口名称getUparEleInRectByTimeAndVertical接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选数据代码字符串数据代码的英文标识UPAR_GLBMUL_FTM表示：全球高空定时值数据必选要素代码字符串分隔表示：检索温度、气压数据必选意义字符串分隔表示：标准气压层必选minLat起始纬度浮点数最多4位小数表示：北纬32.1度必选maxLat终止纬度浮点数最多4位小数表示：北纬40.3度必选minLon起始经度浮点数最多4位小数表示：东经120.5度必选maxLon终止经度浮点数最多4位小数表示：东经130.0度必选7GB/T42877—2023A.1.3气象灾害资料服务接口示例表A.3给出了指定时间段、台风编号(国际)的台风资料检索接口示例。接口名称getTyphByTimeRangeAndTyphGids接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选dataCode数据代码字符串数据代码的英文标识SEVP_WEFC_TYP_WT表示：台风服务产品必选timeRange时间段字符串前开后开：YYYYMMDDHHMISS)前开后闭：YYYYMMDDHHMISS]前闭后开：YYYYMMDDHHMISS)前闭后闭：YYYYMMDDHHMISS]20080102000000]表示：2008年1分00秒(不含)到(含)必选typhGlds台风编号(国际)字符串多个以逗号(,)分隔WP242020表示：2020年西太平洋第24个检测对象必选编报中心字符串多个以逗号(,)分隔ECED表示：欧洲中期数值预报中心必选A.2格点类数据服务接口示例A.2.1数值预报产品格点场要素服务接口示例接口名称getNafpEleGridByTimeAndLevelAndValidtime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选dataCode数据代码字符串标识NAFP_FOR_FTM_LOW_T639_NE-HE表示：T639模式东北半球低分辨率产品必选时间(单个)字符串YYYYMMDDHH-MISS20080101000000表示：起报时间2008必选8接口名称getNafpEleGridByTimeAndLevelAndValidtime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选fcstEle预报要素(单字符串—表示：检索温度要素必选festLevel预报层次(单整数气压层次的整数值，单位：百帕表示：检索1000百帕气压层必选validTime预报时效(单整数预报时效，单位：小时表示：自起报时间预报时效为24小时必选A.2.2数值预报产品经纬度点要素服务接口示例接口名称getNafpEleGridByTimeAndLevelAndValidtime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选dataCode数据代码字符串标识NAFP_FORT639_NEHE必选时间(单个)字符串YYYYMMDDHH-MISS20080101000000表示：起报时间2008必选fcstEle预报要素(单字符串表示：检索温度要素必选fcstLevel预报层次(单整数气压层次的整数值，单位：百帕表示：检索1000百帕气压层必选minVT时效整数预报时效，单位：小时表示：自起报时间预报时效为24小时必选maxVT时效整数预报时效，单位：小时表示：自起报时间预报时效为48小时必选经纬度点字符串多个经纬度点以逗号(,)分隔32.1/120.2表示：北纬32.1度，东经120.2度的点必选A.3信息类数据服务接口示例A.3.1天气雷达资料服务接口示例表A.6给出了指定时间段的天气雷达资料检索接口示例。9表A.6指定时间段的天气雷达资料检索接口示例接口名称getRadaFileByTimeRange接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选数据代码字符串数据代码的英文标识RADA_L2_FMT表示：单站雷达基数据必选时间段字符串前开后开：(YYYYMM-DDHHMISS,YYYYM-MDDHHMISS)前开后闭：(YYYYMM-DDHHMISS,YYYYM-MDDHHMISS]前闭后开：[YYYYMM-DDHHMISS,YYYYM-MDDHHMISS)前闭后闭：[YYYYMM-DDHHMISS,YYYYM-MDDHHMISS]20080102000000]表示：2008年1月1(不含)到2008年100秒(含)必选A.3.2卫星气象资料服务接口示例表A.7给出了指定时间的卫星气象资料检索接口示例。表A.7指定时间的卫星气象资料检索接口示例接口名称getSateFileByTime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选数据代码字符串标识SATE_GEO_IM-AGE_MTR2R表示：MTR2R卫星地球同步轨道图片产品必选时间字符串YYYYMMDDHH-MISS表示：起报时间2008必选A.3.3数值预报产品服务接口示例表A.8给出了指定时间、预报要素的数值预报产品文件检索接口示例。表A.8指定时间、预报要素的数值预报产品文件检索接口示例接口名称getNafpFileByElementAndTime接口参数名称含义赋值类型赋值格式赋值示例使用说明必选/可选数据代码字符串标识NAFP_FOR_FTM_LOW_T639_NEHE表示：T639模式东北半球低分辨率产品必选时间(单个)字符串YYYYMMDDHH-MISS表示：起报时间2008必选预报要素字符串多个以逗号(,)分隔表示：检索温度、气压数据必选GBGB/T42877-2023(规范性)接口参数定义接口参数定义应符合表B.1的规定。表B.1接口参数定义二类别序号参数名称含义赋值类型赋值格式赋值示例使用说明数据代码类1数据代码(单字符串单个SURF_CHN_MUL_HOR表示：中国地面逐小时数据2021第5章的规定要素范围类2代码字符串多个以逗号(,)分隔PRE_1h,TEM表示：小时降水、气温不应用ALL和×3代码字符串格式：统计函数_要素代码，多个以逗号(,)分隔表示：小时降水的累计值，气温的平均值统计函数包括：SUM、MAX、MIN、AVG、COUNT4要素值范围字符串以分号(;)分隔。其中，要素值范围的格式：(a,):大于a;(a,):大于或等于a;(,a):小于a;(,a):小于或等于a;(a,b):大于a,小于b;(a,b):大于或等于a,小于b;[a,b]:大于a,小于或等于b;[a,b]:大于或等于a,小于或等于bVIS:(,1000);RHU:(70,)表示：能见度小于1000m,相对湿度大于70%类别序号参数名称含义赋值类型赋值格式赋值示例使用说明要素范围类5statEleValueRanges统计值范围字符串其中，要素值范围的格式；(a,):大于a:(a,):大于或等于a;(,a):小于a;(,a):小于或等于a;(a,b):大于a,小于b;(a,b):大于或等于a,小于b;(a,b):大于a,小于或等于b;[a,b]:大于或等于a,小于或等于bSUM_PRE_1h:(50,)表示：累计降水大于或等于50mm统计要素代码取自statEles时间范围类6时间(单个)字符串YYYYMMDDHHMISS20150101000000表示：2015年1月1日00时(整点)年月日时分秒应补全7times时间字符串YYYYMMDDHHMISS,多个以逗号(,)分隔20150101000000,20150101010000,20150101020000表示：2015年1月1日00时、01时、02时共3个整点年月日时分秒应补全8timeRange时间段字符串前开后开：(YYYYMMDDHHMISS,YYYYM-MDDHHMISS);前开后闭：(YYYYMMDDHHMISS,YYYYM-MDDHHMISS];前闭后开：[YYYYMMDDHHMISS,YYYYM-MDDHHMISS);前闭后闭：[YYYYMMDDHHMISS,YYYYM-MDDHHMISS](20150101000000,20150102000000)表示：大于2015年1月1日00时(整点),小于或等于2015年1月2日00时(整点)年月日时分秒应补全表B.1接口参数定义(续)云类别序号参数名称含义赋值类型赋值格式赋值示例使用说明时间范围类9minWindow时间窗(分钟)整数180min的时间段单位：分钟(minminSeparate分钟取整条件(分钟)整数表示：0min,10min,20min,30min,40min,50,min的数据与timeRange配合使用hourSeparate小时取整条件(小时)整数6表示：00,06,12,18时的数据与timeRange配合使用validTime预报时效(单个)整数表示：24小时预报单位：小时(h)validTimes预报时效字符串多个以逗号(,)分隔表示：03、06、09时3个预报时效单位：小时(h)minVT起始预报时效整数0表示：起始预报时效为0时单位：小时(h)maxVT终止预报时效整数表示：终止预报时效为168时单位：小时(h)minMD起始月日(历年同期)字符串MMDD表示：1月1日maxMD截止月日(历年同期)字符串MMDD表示：12月31日minYear起始年(历年同期)整数YYYY表示：2001年maxYear截止年(历年同期)整数YYYY表示：2016年daysOfYear日序字符串要素值范围取值：1～365(平年),1～366(闰年)。多个以逗号(,)分隔表示：第1,4,365天仅用于累年日值数据类别序号参数名称含义赋值类型赋值格式赋值示例使用说明时间范围类pensOfYear候序字符串要素值范围取值1～72。多个以逗号(,)分隔表示：第1,10.72候仅用于累年侯值数据旬序字符串要素值范围取值1～36。多个以逗号(,)分隔表示：第1,12,36旬仅用于累年旬值数据monsOfYear月序字符串要素值范围取值1～12。多个以逗号(,)分隔表示：1,4,12月仅用于累年月值数据日序段字符串要素值范围取值：1～365(平年),1~366(闰年)。其中，要素值范围的格式：(a,):大于a;(a,):大于或等于a;(,a);小于a:[,a]:小于或等于a:(a,b):大于a,小于b;(a,b):大于或等于a,小于b;[a,b]:大于a,小于或等于b;[a,b]:大于或等于a,小于或等于b表示：日序大于1小于365仅用于累年日值数据penRangeOfYear候序段字符串要素值范围取值1～72。其中，要素值范围的格式：(a,):大于a;(a,):大于或等于a;(,a):小于a:[,a]:小于或等于a;(a,b):大于a,小于b;(a,b):大于或等于a,小于b;[a,b]:大于a,小于或等于b;[a,b]:大于或等于a,小于或等于b表示：候序大于1小于72仅用于累年侯值数据表B.1接口参数定义(续)示类别序号参数名称含义赋值类型赋值格式赋值示例使用说明时间范围类tenRangeOfYear旬序段字符串要素值范围取值1～36。其中，要素值范围的格式：(a,):大于a;(a,):大于或等于a:(,a):小于a:(,a):小于或等于a;(a,b):大于a,小于b;(a,b):大于或等于a,小于b;(a,b):大于a,小于或等于b;[a,b]:大于或等于a,小于或等于b表示：旬序大于1,小于或等于36仅用于累年旬值数据monRangeOfYear月序段字符串要素值范围取值1～12。其中，要素值范围的格式：(a,);大于a:[a,]:大于或等于a;(,a):小于a;[,a]:小于或等于a;(a,b):大于a,小于b;(a,b):大于或等于a,小于b;(a,b):大于a,小于或等于b;[a,b]:大于或等于a,小于或等于b表示：月序大于1,小于12仅用于累年月值数据空间范围类站号字符串多个以逗号(,)分隔54511.58238表示：北京站和南京站minStald起始站号字符串表示：从54511站(含)开始maxStald终止站号字符串表示：到58238站(含)为止minLon起始经度浮点数最多4位小数表示：经度从116.3°(含)开始单位：度(°);取值范围：(0,360)类别序号参数名称含义赋值类型赋值格式赋值示例使用说明空间范围类maxLon终止经度浮点数最多4位小数表示：经度到118.25°(含)为止单位：度();取值范围：(0,360)minLat起始纬度浮点数最多4位小数31.14表示：纬度从31.14°(含)开始单位：度();取值范围：[—90,90_maxLat终止纬度浮点数最多4位小数39.56表示：纬度到39.56°(含)为止单位：度():取值范围：[—90,90_经纬度点字符串多个以逗号(,)分隔39.56/116.3表示：纬度为39.56°、经度为116.3°的点单位：度();纬度范围：[-90,90];经度范围：(0.360)netCodes台站站网字符串多个以逗号(,)分隔表示：地面观测站气象台站站网符合QX/T37-2020中表3的规定staLevels台站级别字符串多个以逗号(,)分隔表示：国家级基准站台站级别符合QX/T37—2020中表3的规定adminCodes国内行政编码字符串多个以逗号(,)分隔表示：北京市国内行政编码符合GB/T2260-2007中表1的规定nationCodes国家代码字符串多个以逗号(,)分隔表示：中国国家代码应符合GB/T2659—2000中表1的规定townCodes镇代码字符串多个以逗号(,)分隔表示：北京市东城区镇代码符合GB/T2260的规定basinCodes流域编码字符串多个以逗号(,)分隔DA表示：黄河流域流域编码见HJ932—2017《中国地表水环境水体代码编码规则》中的全国流域区划代码表reportCenters编报中心字符串多个以逗号(,)分隔ECED表示：欧洲中期数值预报中心编报中心符合QX/T202-2013附录B的规定verticals垂直探测意义字符串多个以逗号(,)分隔65536表示：标准气压层垂直探测意义见《气象观测报告的解码规则与算法》中表B.1接口参数定义(续)号类别序号参数名称含义赋值类型赋值格式赋值示例使用说明空间范围类pLayers气压层次字符串多个以逗号(,)分隔500.700.850表示：500hPa、700hPa、850hPa三个气压层单位：百帕(hPa);气压层次见WMO.ManualminPLayer气压层次下限整数表示：850hPa气压层单位：百帕(hPa);306).VolumeI.2,代码表3.15maxPLayer气压层次上限整数表示：100hPa气压层单位：百帕(hPa);306).VolumeI.2,代码表3.15hLayers高度层次字符串多个以逗号(,)分隔表示：5000m高度层单位：米(m);高度层次见WMO.ManualminHLayer高度层次下限浮点数表示：最低层次为15m单位：根据数据种类内容确定maxHLayer高度层次上限浮点数表示；最高层次上限200hPa单位：根据数据种类内容确定minFLayer飞行高度层次下限浮点数表示：高度层次下限为1200m单位：米(m);用于飞机报数据maxFLayer飞行高度层次上限浮点数表示：高度层次上限为6000m单位：米(m);用于飞机报数据土壤深度整数表示：土壤深度为320cm单位：厘米(cm);用于农气数据GB/TGB/T42877-2023类别序号参数名称含义赋值类型赋值格式赋值示例使用说明特殊属性类(台风资料参数)typhGIds台风编号(国际)字符串多个以逗号(,)分隔WP242020表示：2020年西太平洋第24个检测对象typhCIds台风编号(国内)字符串多个以逗号(,)分隔2022表示：2020年第22个热带气旋typhNames台风名称字符串多个以逗号(,)分隔VAMCO表示：台风名称为VAMCO特殊属性类(数值预报产品参数)fcstEle预报要素(单个)字符串TEM表示：温度预报要素应符合QX/T102-2009表5的规定fcstEles预报要素字符串多个以逗号(,)分隔PRE,PRS表示：降水量，气压预报要素应符合QX/T102-2009表5的规定fcstLevel预报层次(单个)字符串表示：1000hPa单位：百帕(hPa)fcstLevels预报层次字符串多个以逗号(,)分隔850.1000表示：850hPa和1000hPa单位：百帕(hPa)fcstArea预报区域(单个)字符串GLB表示：全球预报区域应符合GB/T40153-2021表2的规定fcstAreas预报区域字符串多个以逗号(,)分隔SHE,NHE表示：南半球和北半球预报区域应符合GB/T40153—2021表2的规定特殊属性类(天气雷达资料参数)radarScans扫描方式字符串多个以逗号(,)分隔PPI表示：圆锥扫描模式radarRects覆盖范围字符串多个以逗号(,)分隔表示：230kmradarElevs仰角字符串多个以逗号(,)分隔表示：仰角为1.5°单位：度(°)表B.1接口参数定义(续)类别序号参数名称含义赋值类型赋值格式赋值示例使用说明特殊属性类(天气雷达资料参数)minRadarElev最小仰角字符串表示：最小仰角为1.5°单位：度(°)maxRadarEley最大仰角字符串表示：最大仰角为6单位：度(°)radarResos分辨率字符串多个以逗号(,)分隔1表示：空间分辨率为1km单位：千米(km)特殊属性类(卫星气象资料参数)satelliteNames卫星标识字符串多个以逗号(,)分隔FY1-A表示：风云1号A星卫星标识符合QX/T327—2016表1的规定channels卫星通道字符串多个以逗号(,)分隔VIS表示：可见光通道卫星通道符合QX/T327—2016表A.2的规定仪器标识字符串多个以逗号(,)分隔VASS表示：大气垂直探测系统仪器标识符合QX/T327—2016表A.2的规定projectNames投影方式字符串多个以逗号(,)分隔AEA表示：等面积投影投影方式符合QX/T327—2016表6的规定sevpProdCodes服务产品代码字符串多个以逗号(,)分隔CMR]表示：实景监测服务产品代码符合QX/T3782017中表A.3的规定其他类录数整数表示：最多返回10条orderBy排序字段字符串格式：要素代码/排序方向，多个以逗号(,)分隔；排序方向包括：asc(升序)、desc(降TEM/asc表示：按气温升序；SUM_PRE_1h/desc表示：按累计降水降序要素代码可以是普通要素(elements),也可以是统计要素(statEles)distinct返回唯一值(去重复)字符串true或falsetrue表示：去掉重复记录默认是distinct=false,不可范围”同时使用(规范性)返回码取值含义返回码的取值含义应符合表C.1的规定。其他返回码宜根据需要按照返回码的取值含义扩展。表C.1返回码取值含义类别取值含义(英文)含义(中文)备注成功类0Callsucceed调用成功有数据返回失败类Nodataisretrieved无数据返回(没有所需条件范围的数据)错误类别：没有数据-1001MissinguserID用户名缺失错误类别：用户验证失败-1002Invaliduser用户名不存在-1003Missingpassword密码缺失-1004Passworderror密码错误-2001InterfacelDerror接口名错误错误类别：接口与数据不匹配-2002DataCodeerror数据代码错误-3001Parametervalueerror参数赋值错误错误类别：接口参数错误-3002Missingparameter参数缺失-3003Uselessparameter参数多余或未定义-4001Norighttoaccessthedata没有访问该数据的权限错误类别：没有访问权限-4002Norighttoaccessthehistorydata没有访问该历史数据的权限-5001检索的时间跨度超过范围错误类别：单次请求范围过大-5002Timeparameternumberexceeds检索的时间点个数超过限制-6001Failedtoconnectserver服务器连接失败错误类别：服务器连接错误-7001错误类别：数据库操作错误-8001Filedoesnotexist文件不存在错误类别：数据文件错误-8002Filecannotberead文件不可读-9001接口基础功能处理异常错误类别：服务器处理错误-9002Failedtoprocessparameter接口参数处理异常-10001Otherexceptionofserver服务器其他异常错误类别：其他错误GB/T42877—2023(规范性)返回数据结构D.1结构描述说明语言，表示接口的内存对象结构及其序列化格式。其中，内存对象结构为接口返回的寄存在内存中的数据结构，宜直接被程序调用；序列化字符串包括XML、JSON、JSONP、TEXT、HTML等格式；Python等其他语言和xarray等其他序列化格式的表示，参照使用。返回文件内容信息；接口调用客户端获取URL后，使用通用的HTTP、TDS等服务协议去获取文件内容信息，信息类结构适用NetCDF、GRIB1/2等文件格式。D.2站点类返回数据结构D.2.1内存对象结构：RetArray2D站点类返回数据的内存对象结构RetArray2D信息，包括数组、记录数、字段数、接口调用过程信息等，应符合表D.1的规定。表D.1站点类返回数据的内存对象结构RetArray2D信息结构名称RetArray2D使用说明适用于检索站点类数据、格点类数据中单点或多点的要素值、台站元数据信息等接口Fortran结构体成员成员名称requestInfoRequestInfoFortran类型Character(*,*,*)Type(RequestInfo)成员说明长度rowCount,二维长度colCount记录数字段数接口调用过程信息，包括返回码、错误信息、请求的参数、请求接收合D.5的规定类成员成员名称requestInfoC#/Java类型RequestInfo成员说明获取的数据接口调用过程信息，包括返回码、错误信息、请求的参数、请求接收时间、结果返回时间、耗时等，应符合D.5的规定D.2.2序列化格式站点类返回数据的XML、JSON、JSONP、TEXT、HTML等几类格式信息，包括数据和接口调用过程信息等，应符合表D.2的规定。表D.2站点类返回数据的序列化格式信息格式类型格式信息《DSreturnCode="返回码"returnMessage="返回码说明(含错误信息)"rowCount="返回数据行数"colCount="返回数据列数"requestParams="调用参数"requestTime="接收请求时间"responseTime="返回请求结果时间"takeTime="耗时(毫秒)"〉(R字段名1="字段值1"字段名2="字段值2"……字段名n="字段值n"/〉(R字段名1="字段值1"字段名2="字段值2"……字段名n="字段值n"/>(!--其他行数据，此处省略--〉{returnCode:"返回码",returnMessage:"返回码说明(含错误信息)",rowCount:"返回数据行数",colCount:"返回数据列数",requestParams:"调用参数",requestTime:"接收请求时间",responseTime:”返回请求结果时间",takeTime:"耗时(毫秒)",DS:[{字段名1:"字段值1",字段名2:"字段值2",字段名3:"字段值3",……},《字段名1:"字段值1",字段名2:"字段值2",字段名3:"字段值3",……},……//其他行数据，此处省略]}回调函数名称({returnCode:”返回码",returnMessage:”返回码说明(含错误信息)",rowCount:"返回数据行数",colCount:"返回数据列数",requestParams:"调用参数",requestTime:"接收请求时间",responseTime:"返回请求结果时间",takeTime:"耗时(毫秒)",DS:[{字段名1:”字段值1”,字段名2:”字段值2”,字段名3:”字段值3”,……},字段名1:”字段值1”,字段名2:”字段值2”,字段名3:”字段值3”,……},……//其他行数据，此处省略]表D.2站点类返回数据的序列化格式信息(续)格式类型格式信息//注：第1行，调用信息returnCode="返回码"returnMessage="返回码说明(含错误信息)"rowCount="返回数据行数'colCount="返回数据列数"requestParams="调用参数"requestTime="接收请求时间"responseTime="返回请求结果时间"takeTime="耗时(毫秒)"//注：第2行，返回字段列表字段名1字段名2字段名3字段名4字段名5字段名6字段名7……//注：第3-n行，每行对应一条数据记录字段值1字段值2字段值3字段值4字段值5字段值6字段值7……<td)字段名1(/td〉<td)字段名2(/td〉<td〉字段名3</td><!-其他字段，省略-一〉<td)字段值1(/td><td)字段值2(/td><td〉字段值3</td><!--其他字段，省略--〉<td)字段值1(/td><td)字段值2(/td>(td>字段值3</td><!-其他字段，省略--〉<!--其他行数据，此处省略--〉D.3格点类返回数据结构格点类返回数据的内存对象结构RetGridArray2D信息，包括数组、网格定义、接口调用过程信息结构名称RetGridArray2D使用说明适用于检索站点类数据、格点类数据中单点或多点的要素值、台站元数据信息等接口表D.3格点类返回数据的内存对象结构RetGC/C++/Fortran结构体成员成员名称startLatstartLonendLatendLonlatCountlonCountrequestInfoC/C++类型float[][-floatfloatfloatfloatfloatfloatRequestInfoFortran类型Real(*,realrealrealrealrealrealType(Request成员说明获取的数二维长度始纬度始经度束纬度束经度纬向格点数点数纬度格距经度格距程信息，包括返回码、错误信息、请求的参数、请求接收时间、结果返回时间、耗时等，应符合规定C#/Java类成员成员名称startLatstartLonendLatendLonlatCountlonCountrequestInfoC#/Java类型floatfloatfloatfloatfloatfloatfloatRequestInfo成员说明度从西到二维长度始纬度始经度束纬度束经度纬向格点数点数纬度格距经度格距程信息，包括返回码、错误信息、请求的参数、请求接收时间、结果返回时间、耗时等，应符合规定D.3.2序列化格式GB/T42877—2023表D.4格点类返回数据的序列化格式信息格式类型格式信息XML<?xmlversion="1.0"encoding="UTF-8"?><DSreturnCode="返回码"returnMessage="返回码说明(含错误信息)"startLat="网格起始纬度"startLon="网格起始经度"endLat="网格结束纬度"endLon="网格结束经度"latCount="纬向格点数"lonCount="经向格点数"latStep="纬度格距"lonStep="经度格距"requestParams="调用参数"requestTime="接收请求时间”responseTime=”返回请求结果时间"takeTime="耗时(毫秒)"〉<R>值1,值2,值3,……值n</R〉<R>值1,值2,值3,……值n</R><!--其他行数据，此处省略--)JSON{returnCode:“返回码”,returnMessage:"返回码说明(含错误信息)",startLat:"网格起始纬度",startLon:”网格起始经度",endLat:"网格结束纬度",endLon:"网格结束经度",latCount:"纬向格点数",lonCount:"经向格点数",latStep:"纬度格距",lonStep:"经度格距",requestParams:"调用参数",requestTime:"接收请求时间",responseTime:“返回请求结果时间”,takeTime:”耗时(毫秒)”,DS:[[字段值1,字段值2,字段值3,……],[字段值1,字段值2,字段值3,……],……//其他行数据，此处省略]}JSONP回调函数名称({returnCode:"返回码",returnMessage:"返回码说明(含错误信息)",startLat:"网格起始纬度",startLon:”网格起始经度",endLat:"网格结束纬度",endLon:"网格结束经度",latCount:"纬向格点数",lonCount:"经向格点数",latStep:"纬度格距",lonStep:"经度格距",requestParams:"调用参数",requestTime:"接收请求时间",responseTime:"返回请求结果时间",takeTime:"耗时(毫秒)",DS:[[字段值1,字段值2,字段值3,……],[字段值1,字段值2,字段值3,……],……//其他行数据，此处省略]TEXT//注：第1行，调用信息returnCode=“返回码”returnMessage="返回码说明(含错误信息)"startLat="网格起始纬度"startLon="网格起始经度"endLat="网格结束纬度"endLon="网格结束经度"latCount="纬向格点数"lonCount="经向格点数"latStep="纬度格距"lonStep="经度格距"requestParams="调用参数"requestTime=”接收请求时间”responseTime=”返回请求结果时间”takeTime=“耗时(毫秒)”//注：第2-n行，每行对应一条数据记录值1值2值3值4值5值6值7……表D.4格点类返回数据的序列化格式信息(续)格式类型格式信息HTML(td〉纬度\经度</td)<td)经度1</td><td〉经度2(/td><!-其他值省略--〉<td〉纬度1</td〉<td>值1</td)<td>值2</td〉<!-其他值省略--〉<td〉纬度2</td><td>值1</td)<td>值2</td)<!-其他值省略--〉(!-其他行数据，此处省略--〉D.4信息类返回数据结构信息类返回数据的内存对象结构RetFilesInfo信息，包括文件信息清单、文件数、接口调用过程信结构名称RetFilesInfo使用说明适用于检索文件列表信息的接口，一般为非结构化预报文件和图形文件等C/C++/Fortran结构体成员成员名称filelnfosfileCountrequestInfoC/C++类型FileInfo[]RequestInfoFortran类型Type(Filelnfo)(*)Type(RequestInfo)成员说明检索下载的文件信息清单，长度：fileCount,应符合表D.6规定获取的文件数接口调用过程信息，包括返回码、错误信息、请求的参数、请求接收时间、结果返回时间、耗时等，应符合D.5的规定C#/Java类成员成员名称fileInfosrequestInfoC#/Java类型Filelnfo[]RequestInfo成员说明检索下载的文件信息清单。应符合表D.6的规定接口调用过程信息，包括返回码、错误信息、请求的参数、请求接收时间、结果返回时间、耗时等，应符合附录D.5的规定GB/T42877—2023D.4.2单个文件信息的内存对象结构：FileInfo单个文件信息的内存对象结构Filelnfo信息，包括接口调用客户端文件名、全路径、文件后缀、文件大小、接口服务端文件URL等，应符合表D.6的规定。表D.6单个文件信息的内存对象结构FileInfo信息结构名称Filelnfo使用说明描述单个文件的信息。RetFilesInfo中的成员filelnfos,是本数据结构的数组Fortran结构体成员成员名称类型Fortran类型CharacterCharacter(*)CharacterCharacterCharacter(*)Character(*,成员说明接口调用客户端文件名(含后接口调用客户端文件全路径名(路径十文件名)。在仅获取文件信息列表员为空文件后缀文件URLbase64编码数除固定输出的要素类成员成员名称类型成员说明文件名(含后缀)文件全路径名文件后缀服务端文base64编码数除固定输出的要素D.4.3序列化格式信息类返回数据的XML、JSON、JSONP、TEXT、HTML等几类格式信息，包括文件信息清单、文件数、接口调用过程信息等，应符合表D.7的规定。表D.7信息类返回数据的序列化格式信息格式类型格式信息XML<?xmlversion="1.0"encoding="UTF-8"?><DSreturnCode="返回码"returnMessage="返回码说明(含错误信息)"fileCount="文件数"requestParams=“调用参数”requestTime="接收请求时间"responseTime="返回请求结果时间"表D.7信息类返回数据的序列化格式信息(续)格式类型格式信息takeTime="耗时(毫秒)"〉<RfileName=""fileUrl=""suffix=""size=""imgBase64=""attributesl=""…attributesn=""/)<RfileName=""fileUrl=""suffix=""size=""imgBase64=""attributesl=""…attributesn=""/)<!-其他行数据，此处省略--〉{returnCode:“返回码”,returnMessage:“返回码说明(含错误信息)”,fileCount:"文件数",requestParams:“调用参数",requestTime: