首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API · 联合国条约系列接口接入指南

数据鱼API · 联合国条约系列接口接入指南

原创
作者头像
用户12862874
发布于 2026-11-20 21:55:13
发布于 2026-11-20 21:55:13
100
举报

接口简介

「联合国条约系列」是数据鱼API平台提供的条约卷册目录查询接口,Base 路径 /api/legal-un-treaty-series,共 3 个端点。它以卷为单位组织条目,每条记录包含卷号、标题、年份或年份区间、语言列表与内容描述,支持按关键词和卷号检索,可用于资料索引、目录浏览与内部知识库的条目补全。

接口的数据模型是扁平的卷册条目,而不是条约全文库:记录里没有条文、签署方、生效状态、保留声明等字段,也不提供全文下载或引用跳转。检索在标题与描述两个文本字段上做不区分大小写的子串匹配,卷号则要求精确相等;两个条件可以同时使用,结果为交集。

条目整理自公开条约/标准信息,以联合国、WIPO 官方文本为准。数据鱼API提供的是检索与索引能力,不替代官方出版物,也不对条约的现行效力作判断。

端点总览

方法

路径

说明

鉴权

GET

/api/legal-un-treaty-series/ping

健康检查,返回版本与服务器时间

免鉴权

GET

/api/legal-un-treaty-series/info

返回数据集名称、说明与更新日期

需要 Key

GET

/api/legal-un-treaty-series/search

按关键词或卷号检索卷册条目

需要 Key

通用约定

鉴权使用平台统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递;未携带返回 4011,无效返回 4013。响应统一为 code、msg、data 三段。GET 与 POST 在网关层都可使用,POST 支持 JSON body 或表单,参数名与查询串一致。

错误码包括 4001 缺少必填参数、4002 参数格式或取值非法、4003 取值不在支持列表、4004 查询目标未收录,以及 4040 路由不存在、4050 方法不允许、5000 与 5001 服务内部错误。5031、5032 表示上游依赖不可用,接口不会用编造数据顶替。数据鱼API的参数类错误不计入服务故障。

核心端点详解

系列信息

GET /api/legal-un-treaty-series/info 无参数,返回数据集的自描述信息,适合在页脚或关于页展示数据口径。

参数

类型

必填

默认值

说明

无

—

—

—

该端点不接受业务参数

响应 data 包含 name、description、total_volumes_mock 与 last_updated。name 为 United Nations Treaty Series (UNTS) API,description 说明其提供 UNTS 已出版卷册与条约的信息,total_volumes_mock 为 3000,last_updated 为 2026-11-11。

代码语言:javascript
复制
GET /api/legal-un-treaty-series/info?api_key=YOUR_KEY

关键词与卷号检索

GET /api/legal-un-treaty-series/search 在标题与描述中查找关键词,并可用卷号收窄结果。

参数

类型

必填

默认值

说明

q

string

否

—

搜索关键词,匹配条约标题或描述,不区分大小写

volume

integer

否

—

卷号,精确匹配

两个参数都可省略;只传 q 时返回所有标题或描述命中的条目,只传 volume 时返回该卷,两个都传时取交集。响应 data 是数组,每个元素含 volume、title、date、languages 与 description。languages 是字符串数组,date 可能是单一年份,也可能是 1946-1947 这样的区间字符串。

代码语言:javascript
复制
GET /api/legal-un-treaty-series/search?q=Treaties&volume=2100&api_key=YOUR_KEY

该例命中卷 2100 的 Multilateral Treaties,其语言为 English 与 French,描述指向 1999 年末至 2000 年初登记的多边协定。

数据与限制

  • total_volumes_mock 为 3000,字段名带 mock 标记,表示目录规模的口径值,不是当前可检索的记录数。
  • 当前可检索的样本条目为三卷:卷 1、卷 2100 与卷 2600;未包含的卷号查询会得到空数组。
  • 卷 1 的 date 为 1946-1947,卷 2100 为 2000,卷 2600 为 2009,均为字符串,不保证可直接解析为日期。
  • q 只匹配 title 与 description,不搜索卷号、日期或语言名称,也不做词干还原与拼写纠错。
  • volume 按宽松相等比较,传入字符串或整数均可,但建议只传整数字面量。
  • 没有分页、排序与总数统计字段;结果按内置顺序返回,最多覆盖当前样本集。
  • last_updated 固定为 2026-11-11,反映数据集整理日期,不是条约签署或登记日期。
  • 所有端点都不缓存调用方结果,也不提供增量更新接口。

典型使用场景

  • 国际法研究或教学场景中,按关键词浏览条约卷册目录,快速定位某一主题所在的卷号。
  • 企业内部知识库为已有的条约条目补全标题、语言与简介,减少人工录入。
  • 数据看板或资料页展示数据集说明与更新时间,帮助读者判断索引的新旧程度。

注意事项

  • 文档的统一响应写成功 code 为 0,但 info 与 search 的实现返回 code 为 200;ping 返回 0。接入时应同时接受 0 与 200,或按端点分别判断。
  • total_volumes_mock 的 3000 与实际样本三卷差距很大,不要把该数字当作可查询总量对外展示。
  • 卷号不存在时接口返回空数组而非 4004,调用方需要自行区分「无匹配」与「参数错误」。
  • q 传空字符串会被当作命中所有条目,等同于不筛选;需要「无结果」语义时应传一个不可能出现的词或在前端拦截空值。
  • 检索结果是目录级摘要,不含条约正文、附件、签署方与生效信息;引用前应回到官方文本核对。
  • 数据鱼API不对条约的适用范围与效力作判断。仅供参考,不构成法律意见,条目整理自公开条约/标准信息,以联合国、WIPO 官方文本为准。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 系列信息
    • 关键词与卷号检索
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档