MZ T 164-2020 地名信息库数据访问接口规范.pdf

《MZ T 164-2020 地名信息库数据访问接口规范.pdf》由会员分享，可在线阅读，更多相关《MZ T 164-2020 地名信息库数据访问接口规范.pdf（17页珍藏版）》请在麦多课文档分享上搜索。

1、 发芽，早 三 ICS 35.240.99 CCS L 72 备案号 ： 中 华 人 民 共 和 国 民 政 行 业 标 准 MZ MZ/T 164 2020 地名信息 库数据访 问接口规 范 Data Access interface specification for database of geographical names 2020-12-22 发布 2020-12-22 实施 中 华 人 民 共 和 国 民 政 部 发布 MZ/T 164 2020 I 目 次 前 言 . II 1 范围 .1 2 规范性 引用 文件 .1 3 术语和 定义 .1 4 接口访 问方 法描 述 .2

2、4.1 总体描 述 .2 4.2 坐标系 .2 4.3 数据类 型 .2 4.4 请求报 文定 义 .2 4.5 响应报 文定 义 .3 4.6 状态码 定义 .4 4.7 接口访 问步 骤 .4 5 数据访 问接 口 .5 5.1 地名查 询接 口 .5 5.2 地名标 志查 询接 口 .6 5.3 地名明 细信 息获 取接 口 .7 5.4 地名标 志明 细信 息获 取接 口 .9 5.5 行政区 划基 础数 据查 询接 口 .10 5.6 地名类 别基 础数 据查 询接 口 . 11 5.7 附件获 取接 口 .12 参 考 文 献 .13 表 1 数据 类型 . 2 表 2 Get 方

3、法 的接 口访 问 方式 . 2 表 3 Post 方 法的 接口 访 问方式 . 3 表 4 响应 报文 解码 后 JSON 数 据结 构 . 3 表 5 响应 报文 解码 后状 态码含 义说 明 . 4 表 6 地名 查询 接口 请求 参数 . 5 表 7 地名 查询 接口 响应 参数 . 5 表 8 地名 标志 查询 接口 请求参 数 . 6 表 9 地名 标志 查询 接口 响应参 数 . 7 表 10 地 名明 细信 息获 取 接口请 求参 数 . 7 表 11 地 名明 细信 息获 取 接口响 应参 数 . 8 表 12 地 名标 志明 细信 息 获取接 口请 求参 数 . 9 表

4、13 地 名标 志明 细信 息 获取接 口响 应参 数 . 9 表 14 行 政区 划基 础数 据 查询接 口请 求参 数 . 10 表 15 行 政区 划基 础数 据 查询接 口响 应参 数 .11 表 16 地 名类 别 基 础数 据 查询接 口请 求参 数 .11 表 17 地 名类 别基 础数 据 查询接 口响 应参 数 .11 表 18 附 件获 取接 口请 求 参数 . 12 MZ/T 164 2020 II 前 言 本文件 按照 GB/T 1.1 2020 标 准化 工作 导则 第 1 部分： 标准 化文 件的 结构 和起草 规则 的 规 定 起草。 请注意 本文 件的 某些 内

5、容 可能涉 及专 利。 本文 件的 发布机 构不 承担 识别 专利 的责任 。 本文件 由中 华人 民共 和国 民政部 提出 。 本文件 由全 国地 名标 准化 技术委 员会 （SAC/TC233 ） 归口。 本文件 起草 单位 ：民 政部 区划地 名司 、厦 门精 图信 息技术 有限 公司 。 本文件 主要 起草 人： 黄智 晖、 朱 永强 、 杨 刚、 龚发 芽、 卢 艇、 贺延 伟、 田瑜 基、 黄 萍萍 、 田 铮、 林 仙梅、 郭燕 滨、 胡鹏 飞。 本文件 为首 次发 布。 MZ/T 164 2020 1 地名信息 库数据 访问 接口 规范 1 范围 本文件 规定 了地 名信 息库

6、 的接口 访问 方法 和数 据访 问接口 。 本文件 适用 于各 级地 名主 管单位 及其 他委 办局 或科 研单位 与地 名信 息库 的数 据对接 。 2 规范性 引用 文件 下列文 件中 的内 容通 过文 中的规 范性 引用 而构 成本 文件必 不可 少的 条款 。 其 中 ， 注日 期的 引用 文件 ， 仅该日 期对 应的 版本 适用 于本文 件； 不注 日期 的引 用文件 ， 其 最新 版本 （包 括所有 的修 改单 ） 适 用 于 本 文件。 GB/T 2260 中 华人 民共 和 国行政 区划 代码 GB/T 10114 2003 县以 下行政 区划 代码 编制 规则 3 术语和

7、定义 下列术 语和 定义 适用 于本 文件： 3.1 地名代 码 codes for geographical names 地名代 码是 表示 一条 地名 的唯一 标识 码。 地名 代码 一 般由地 名所 在的 县级 以上 行政区 划代 码加 县 级 以下行 政 区 划代 码加 地名 类别代 码加 顺序 号四 段数 字组成 ，共 有 20 位 数字 。 来源 ：MZ/T 162 2020 ，7.1.2 ，有 修改 3.2 地名标 志代 码 codes for signs of geographical names 地名标 志代 码是 表示 一条 地名标 志的 唯一 标识 码。 地 名标志 代码

8、 由地 名标 志所 对应地 名的 地名 代 码 加顺序 号组 成， 共 有22 位 数字。 来源 ：MZ/T 162 2020 ，7.1.3 ，有 修改 3.3 JSON Javascript Object Notation JSON 是一 个轻 量级 的， 基 于文本 的， 跨语 言的 数据 交换格 式。JSON 定 义了 一 组用于 表示 结构 化数 据的可 移植 的格 式化 规则 。 来源 ：RFC4627 3.4 WKT Well known text WKT(Well-known text) 是 一种文 本标 记语 言 ， 用于 表示矢 量几 何对 象 、 空间 参照系 统及 空间

9、参照 系 MZ/T 164 2020 2 统之间 的转 换。 来源 ：OGC12 063r5 3.5 Token 本文件 的Token 是指 由服 务端生 成的 一段 字符 串， 该字符 串作 为客 户端 进行 请求的 令牌 ， 服 务端 通 过客户 端携 带的 令牌 ，实 现对客 户端 身份 的识 别和 权限的 控制 。 4 接口访 问方 法描 述 4.1 总体描 述 每个地 名信 息库 数据 接口 对应一 个唯 一 的URL 网址 ，通过 该 URL 对 接口 进行 访问。 本文件 描述的 所有 接口请 求报文 的请求 头（Header ）必须 含有一 个“Token ” 值，用 于校验

10、和确 保 数据来 源安 全性 。接 口的 请求方 式包 括 Get 和 Post 两种， 接口 的响 应报 文正 文返回 格式 为 JSON 格式 。 4.2 坐标系 本文件 中接 口所 涉及 空间 数据均 采 用2000 国 家大 地 坐标系 （CGCS2000）。 4.3 数据类 型 本 文 件 中 接 口 的 调 用 和 数 据 返 回 使 用 了 字 符 型 、 整 型 、 布 尔 型 、 浮 点 型 、 日 期 时 间 型 、 以 及 JavaScript 对 象等 数据 类 型。 表 1 数据 类型 数据类型 说明 String （字符型） 通过字符形式表达的值的类型 Int（整型

11、） 通过 0 到 9 数字表达的整数类型的值， 值在-2147483648 到 2147483647 之间 Bool （布尔型） 通过 True 或 False 表达的类型 Float （浮点型） 通过 0 到 9 数字表达的实数 DateTime （日期时间型） 通过 YYYYMMDDhhmmss 的形式表 达的值的类型 Object （对象类型） JavaScript 中对象数据类型 4.4 请求报 文定 义 表 2 Get 方法 的接 口访 问方式 请求相关 信息 示例值 描述 请求 URL 【接口所 在 URL 网 址】 接口所在 的 URL 地址 请求方式 （Method ） Get

12、 MZ/T 164 2020 3 表 2 Get 方法 的接 口访 问方式 （续 ） 请求相关 信息 示例值 描述 请求头 （Header ） Token 【用户获 取的 Token 值】 用户持有 的 Token ， 用户请求时， 将 Token 放在 Header 里，用于识别用 户和控制 权限 Accept Application/json 表示数据 返回 Json 类型 请求 URL 参数 例如：Page=1&Size=10 用户调用 接口的 参数 ， 具体 的值参考 各个接口 所需的 参数， 所有 参数直接 作为 URL 参 数提交 即可 表 3 Post 方 法的 接口 访 问方式

13、 请求相关 信息 示例值 描述 请求 URL 【接口所 在 URL 网 址】 接口所在 的 URL 地址 请求方式 （Method ） Post 请求头 （Header ） Token 【用户获 取的 Token 值】 用户持有 的 Token ， 用户请 求时 ，将 Token 放在 Header 里， 用于识别用户 和控制权 限 Content-Type Application/json 表示上传 到服务 端的参 数类 型 Accept Application/json 表示数据 返回 Json 类型 请求体（body ） 例如： “Page ”: “1 ”, “Size ”: “1 ”

14、用户调用 接口的 参数 ， 具体 的值参考 各个接口 所需的 参数， 所有 参数组合 为 Json 数据格 式，放 到请求 体 （body），作为请求提 交 4.5 响应报 文定 义 响应报 文输 出参 数解 码 后JSON 数据 结构 如下 ： 表 4 响应 报文 解码 后JSON 数 据结 构 JSON 格式定义 说明 接口响应处理结果状态码，详见4.6 状态码定义 接口响应处理结果，Object 类型 接口响应处理结果集合总条数 接口响应处理结果描述信息 MZ/T 164 2020 4 4.6 状态码 定义 如上文 ，响 应报 文解 码 后Status 即 为状 态码 ，不 同 的状态

15、码表 示不 同的 含义 ，说明 如下 ： 表 5 响应 报文 解码 后状 态码含 义说 明 状态码 定义 备注 0 接口访问处理正常 1 服务端内部错误 2 接口访问权限不足 没有访问该接口的权限 3 请求报文中的参数在服务端验证不通过 传递的参数值存在问题，或缺少必填参数等 4 被限流 一定时间段内超过接口访问最大次数 5 接口访问处理失败 4.7 接口访 问步 骤 接口访 问步 骤如 下： a) 获取授权： 通过地名信息库政务管理 平台注册用户并对相关接口 访问进行申请，经审核通 过 后获取 合法 授权 。 b) 获取接 口地 址： 通过 地名 信息库 政务 管理 平台 获取 接口唯 一

16、的 URL 网址 。 c) 构建接 口访 问地 址： Get 请求 cURL 示例 cURL -X GET -header Accept: application/json -header Token: 【用户获取的 Token 值】 http:/ 【 接口 对应的 URL 地址 】? 【接口 参数 1 】= 【接 口参数值 1 】& 【接口参数 2 】= 【接口 参 数值 2 】 Post 请求cURL 示例 cURL -X POST -header Content-Type: application/json -header Token: 【用户获取的 Token 值】 -header A

17、ccept: application/json -d 【 接口参数 1 】 : 接口参 数值 【接口参数 2 】 【 接口参数值 2 】 【接口对 应的 URL 地址】 d) 接口访 问： 通过 编码 的接 口访问 地址 访问 接口 ，取 得返回 结果 。 MZ/T 164 2020 5 5 数据访 问接 口 5.1 地名查 询接 口 5.1.1 接口描 述 根据用 户输 入合 法的 接口 访问网 址和 参数 ， 对 地名 信息库 中的 地名 进行 查询 。 查询 参数 包括 地名 名 称、地 名类 别代 码、 行政 区划代 码、 使用 时间 等； 查询结 果 以JSON 格 式返 回 。 5

18、.1.2 接口网 址格 式 http:/ 服务地址/api/ 版 本号/PlaceName/List 5.1.3 请求参 数 请求方 式：Get 表 6 地名 查询 接口 请求 参数 参数名称 是否必须 类型 约束 描述（示 例） PlaceName 否 String 小于 200 个字符 搜索的地 名名称 PlaceTypeCode 否 String 符合地名 类别代 码格 式 地名类别 代码 DistCode 否 String 符合行政 区划代 码格 式 行政区划 代码 UseTime 否 String 01 或 02 使用时间 ， “01 ” 表示现 今地 名， “02 ”表示历史 地名

19、 Page 是 Int 大于 0 页码 Size 是 Int 大于 0 每页大小 5.1.4 响应参 数 表 7 地名 查询 接口 响应 参数 参数名称 描述 类型 Status 服务状态 码，值 查看下 述介 绍 Int Rows 接口返回 的数据 集合 Object PlaceCode 地名代码 String StandardName 标准名称 String HasGeometry 是否有坐 标，0 表示 无，1 表示点状 地名，2 表示 线状地 名 Int MZ/T 164 2020 6 表 7 地名 查询 接口 响应 参数 （ 续） 参数名称 描述 类型 Geometry 空间信息 ，

20、内容 为 WKT 标 准格式 String HasMedia 是否有多 媒体 Bool PlaceTypeName 地名类别 全名 String RegistrationTime 登记时间 DateTime UpdateTime 数据更新 时间 DateTime Registranter 登记人 String UseTime 使用时间 “01” 表示 现今地 名， “02 ” 表示历史 地名 String DistName 完整所在 区划名 称 String PlaceTypeCode 地名类别 代码 String Total 请求结果 查询的 总条数 Int Message 接口返回 的文本

21、 消息 String 5.2 地名标 志查 询接 口 5.2.1 接口描 述 根据用 户输 入合 法的 接口 访问网 址和 参数 ， 对 地名 信息库 中的 地名 标志 进行 查询。 查询 参数 包括 地 名标志 名称 、地 名类 别代 码、行 政区 划代 码、 登记 人姓名 等； 查询 结果 以 JSON 格 式返 回。 5.2.2 接口网 址格 式 http:/ 服务地址/api/ 版 本号/PlaceSign/List 5.2.3 请求参 数 请求方 式：Get 表 8 地名 标志 查询 接口 请求参 数 参数名称 是否必须 类型 约束 描述（示 例） PlaceName 否 Strin

22、g 小于 200 个字符 搜索的地 名标志 名称 PlaceTypeCode 否 String 符合地名 类别代 码格式 地名类别 代码 DistCode 否 String 符合行政 区划代 码格式 行政区划 代码 Registranter 否 String 小于 100 个字符 按登记人 姓名检 索 Page 是 Int 大于 0 页码 Size 是 Int 大于 0 每页大小 MZ/T 164 2020 7 5.2.4 响应参 数 表 9 地名 标志 查询 接口 响应参 数 参数名称 描述 类型 Status 服务状态 码，值 查看下 述介 绍 Int Rows 接口返回 的数据 集合 O

23、bject Code 地名标志 代码 String StandardPlaceName 地名标志 名称 String UpdateTime 数据的更 新时间 DateTime Register 登记人 String DistName 完整的行 政区划 名称 String HasGeometry 是否有空 间信息 ，0 表示无 ，1 表示 点状数据 ，2 表示线 状数据 Int HasMedia 是否包含 多媒体 Bool Total 请求结果 查询的 总条数 Int Message 接口返回 的文本 消息 String 5.3 地名明 细信 息获 取接 口 5.3.1 接口描 述 根据用 户输

24、 入合 法的 接口 访问网 址和 地名 代码 （PlaceCode ）, 获取 用户所 在地 的地名 明细 信息 ， 查 询 结果 以JSON 格 式返 回。 5.3.2 接口网 址格 式 http:/ 服务地址/api/ 版本 号/PlaceName/Detail 5.3.3 请求参 数 请求方 式：Get 表 10 地 名明 细信 息获 取 接口请 求参 数 参数名称 是否必须 类型 约束 描述（示 例） PlaceCode 是 String 符合地 名代 码格 式 地名代 码 MZ/T 164 2020 8 5.3.4 响应参 数 表 11 地 名明 细信 息获 取 接口响 应参 数 参

25、数名称 描述 类型 Status 服务状态码 Int Rows 接口返回的数据集合 Object PlaceCode 地名代码 String StandardName 标准名称 String PlaceTypeName 地名类别全名 String RegistrationTime 登记时间 DateTime UpdateTime 数据更新时间 DateTime registranter 登记人 String UseTime 使用时间 “01” 表示现今地名， “02” 表示历史地 名 String DistName 完整所在区划名称 String PlaceTypeCode 地名类别代码 St

26、ring DistCode 所在行政区划代码 String DistNameAll 完整的行政区划名称（包括所在省市） String PlaceNameTypeAll 完整的地名类别（包括大类中类） String Alias 别名 String Abbreviations 简称 String FormerName 曾用名 String ChineseCharacterWriting 汉字书写 String EthnicMinoritiesWriting 少数民族语书写 String PlaceOriginalSound 地名原读音文件路径 String RomanAlphabetSpellin

27、g 罗马字母拼写 String PlaceLanguage 地名语种 String PlaceOrigin 地名来历 String PlaceMeaning 地名含义 String PlaceHistory 地名历史沿革 String EntityProfile 地理实体概况 String MultimediaInfo 多媒体信息文件路径，多个路径间用“| ”隔开 String DataSources 资料来源以及出处 String Comment 备注 String GenRomemSpelling 通名罗马字母拼写 String EstablishmentYear 设立年份 String

28、AbolishYear 废止年份 String Geometry 空间信息，内容为 WKT 标准格 式 String MZ/T 164 2020 9 表 11 地 名明 细信 息获 取 接口响 应参 数 （ 续） 参数名称 描述 类型 Total 请求结果查询的总条数 Int Message 接口返回的文本消息 String 5.4 地名标 志明 细信 息获 取接 口 5.4.1 接口描 述 根据用户输 入合法 的接口 访问网址和 地名标 志代码 （code ）, 获取用 户所在 地 的地名标志 明细信 息， 查询结 果 以JSON 格 式返 回 。 5.4.2 接口网 址格 式 http:/

29、 服务地址/api/ 版 本号/PlaceSign/Detail 5.4.3 请求参 数 请求方 式：Get 表 12 地 名标 志明 细信 息 获取接 口请 求参 数 参数名称 是否必须 类型 约束 描述 （示 例） Code 是 String 符合地 名标 志代 码格 式 地名标 志代 码 5.4.4 响应参 数 表 13 地 名标 志明 细信 息 获取接 口响 应参 数 参数名称 描述 类型 Status 服务状态 码 Int Rows 接口返回 的数据 集合 Object Code 地名标志 代码 String StandPlaceName 地名标志 名称 String UpdateT

30、ime 数据的更 新时间 DateTime Register 登记人 String DistNameAll 完整的行 政区划 名称（ 包括 省市） String Spell 汉语拼音 拼写 String NationWords 民族文字 String Longitude 经度 Float MZ/T 164 2020 10 表 13 地 名标 志明 细信 息 获取接 口响 应参 数 （ 续） 参数名称 描述 类型 Latitude 纬度 Float SetUnit 设立单位 String SetTime 设立时间 String ProduceVender 生产厂家 String Material

31、 材质 String Norms 规格 String PicFname 标志照片 的路径 ，多个 路径 用“| ”隔 开 String RegisterCompany 登记单位 String DistCode 所在区划 代码 String Total 请求结果 查询的 总条数 Int Message 接口返回 的文本 消息 String 5.5 行政区 划基 础数 据查 询接 口 5.5.1 接口描 述 根据用 户输 入合 法的 接口 访问网 址和 参数 ， 对 行政 区划基 础数 据进 行查 询。 查询参 数包 括行 政区 划 代码、 行政 区划 最大 层级 、是否 包含 本级 行政 区划

32、等；查 询结 果 以 JSON 格 式 返回。 5.5.2 接口网 址格 式 http:/ 服务地址/api/ 版 本号/Xzqh/Get 5.5.3 请求参 数 请求方 式：Get 表 14 行 政区 划基 础数 据 查询接 口请 求参 数 参数名称 是否必须 类型 约束 描述（示 例） Code 是 String 符合行政 区划代 码 查询的行 政区划 代码 MaxDeep 否 Int 1 、2 、3 行政区划 最大层 级， 例如：2 表 示获取两 层的深 度 IncludeCurr 否 Bool 是否包含 本级行 政区划 ， 默 认为 否 MZ/T 164 2020 11 5.5.4 响

33、应参 数 表 15 行 政区 划基 础数 据 查询接 口响 应参 数 参数名称 描述 类型 Status 服务状态 码，值 查看下 述介 绍 Int Rows 接口返回 的数据 集合 Object ID 数据的 ID Int Code 区划代码 String Name 区划名称 String Level 级别，0 表示 国家级 ，1 表示省级，2 表 示地市 级，3 表示区 县级，4 表示 乡镇级 Int ParentCode 上一级区 划代码 String Children 下一级节 点的数 据 Object Total 请求结果 查询的 总条数 Int Message 接口返回 的文本 消

34、息 String 5.6 地名类 别基 础数 据查 询接 口 5.6.1 接口描 述 根据用 户输 入合 法的 接口 访问网 址， 直接 返回 所有 层级的 地名 类别 ，查 询结 果以 JSON 格式 返回 。 5.6.2 接口网 址格 式 http:/ 服务地址/api/ 版 本号/placetype/get 5.6.3 请求参 数 请求方 式：Get 表 16 地 名类 别基 础数 据 查询接 口请 求参 数 参数名称 是否必须 类型 约束 描述（示 例） Isall 否 Int 1 表示查询全 部，0 表 示查询下 级 5.6.4 响应参 数 表 17 地 名类 别基 础数 据 查询接 口响 应参 数 参数名称 描述 类型 Status 服务状态 码，值 查看下 述介 绍 Int MZ/T 16