mondo.international

API 参考

整个平台只有一个 REST API。仅提供 JSON,版本置于 /api/v1.

认证

在您的账号页面创建密钥,然后作为 bearer 令牌发送。密钥免费。

curl -H "Authorization: Bearer ec_ab12cd34.YOUR_SECRET" \
  "https://mondo.international/api/v1/datasets"

为无法设置请求头的工具,也接受 X-API-Key 与 ?api_key=。

决定授权的是许可,不是密钥

有效的密钥可让您取得目录。只有当您已就所声明的用途接受了某数据集的许可,才会提供其观测值。若尚未接受,API 会返回 403,并给出您所需的确切许可以及接受它的链接。

{
  "error": {
    "code": "licence_acceptance_required",
    "message": "You have not accepted the licence terms for the requested data...",
    "declined": [{"dataset": "wb-trade-openness", "licence": {"code": "CC-BY-4.0"}, ...}],
    "accept_at": "https://mondo.international/account/"
  }
}

端点

端点权限范围返回内容
GET /api/v1/—服务说明与端点索引
GET /api/v1/meta—语言、限额、行数
GET /api/v1/licences—机器可读的许可登记册
GET /api/v1/sources—提供方及其条款
GET /api/v1/questions—以问题为先的导航,以数据形式呈现
GET /api/v1/datasetscatalog:read目录,含针对每个数据集的访问判定
GET /api/v1/datasets/<slug>catalog:read单个数据集及其指标与新鲜度
GET /api/v1/areascatalog:read带 ISO 代码的地理单元
GET /api/v1/observationsdata:read数据本身。受许可管控。
GET /api/v1/searchcatalog:read与查询匹配的问题、数据集、指标与地区
GET /api/v1/freshnesscatalog:read每个数据集上次刷新的时间及其是否已过期
GET /api/v1/publicationscatalog:read如何引用 Mondo,以及其背后的研究

查询观测值

参数示例备注
datasetwb-trade-openness短标识。此项与 indicator 必须提供其一。
indicatorNE.TRD.GNFS.ZS,NE.EXP.GNFS.ZS以逗号分隔的来源代码
areaCAN,FRA,JPN,CHNISO-3、ISO-2、NUTS 或汇总代码
partnerUSA仅适用于双边序列
start / end2000 / 2024年份,含首尾
usecommercial本次请求所声明的用途;必须为许可所允许
limit / offset5000 / 0上限 50000
langfren, fr, ja, zh

试一试

curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=abs-national-accounts&area=CAN,FRA,JPN&start=2010"
curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=bis-policy-rates&area=CAN,FRA,JPN&start=2010"
curl -H "Authorization: Bearer $EC_KEY" \
  "https://mondo.international/api/v1/observations?dataset=ecb-hicp-inflation&area=CAN,FRA,JPN&start=2010"

响应结构

{
  "count": 45,
  "declared_use": "academic",
  "licences": { "CC-BY-4.0": { "name": "...", "attribution": "..." } },
  "citation": ["Mondo (2026). Trade openness... Licence: CC BY 4.0."],
  "observations": [
    { "dataset": "wb-trade-openness", "indicator": "NE.TRD.GNFS.ZS",
      "area": "CAN", "partner": null, "period": "2024-12-31",
      "value": 67.4, "unit": null, "status": null }
  ]
}

引用什么

每个包含数据的回答还附带两样东西。第一样是 citation 和 licences,标明数据提供方和许可:大多数许可都要求这样署名。第二样是 cite,这是一项请求:平台本身的参考文献,以及其科学主任发表的、与所请求数据最接近的至多四项成果,每项都附有 DOI。如果 Mondo 对您发表的成果有所帮助,欢迎引用本平台;相关研究若与您的主题相关,也欢迎一并引用。这不是使用条件。

"cite": {
  "platform": "Warin, T. (2026). Mondo: open international economic data [Data platform]. CIRANO. https://mondo.international",
  "related_research": [
    { "reference": "Van Assche, A., & Warin, T. (2019). Global Value Chains and Economic Diplomacy. AIB Insights. https://doi.org/...",
      "doi": "...", "url": "https://doi.org/...", "year": 2019 }
  ],
  "all_publications": "https://mondo.international/publications"
}

面向 AI 助手的 MCP 服务器

同一套 API 也通过 Model Context Protocol 提供给 AI 助手。接入的助手可以把搜索目录和读取数据当作工具来使用,其余一切不变:同样的密钥、同样的限额、同样的许可闸门,每个回答都附带引用和许可。

https://mondo.international/mcp

传输方式:Streamable HTTP,JSON 响应,无会话。与 REST API 一样,以 Bearer 令牌发送密钥。获取服务器说明无需密钥;调用工具则需要。

claude mcp add --transport http mondo https://mondo.international/mcp \
  --header "Authorization: Bearer ec_ab12cd34.YOUR_SECRET"
工具返回内容
search与查询匹配的问题、数据集、指标与地区
list_questions以问题为先的导航,以数据形式呈现
list_datasets目录,含针对每个数据集的访问判定
get_dataset单个数据集及其指标与新鲜度
list_areas带 ISO 代码的地理单元
get_observations数据本身。受许可管控。
list_sources提供方及其条款
list_licences机器可读的许可登记册
how_to_cite如何引用 Mondo,以及其背后的研究
data_freshness每个数据集上次刷新的时间及其是否已过期

助手会读取收到的每一行,因此 get_observations 每次调用最多返回 2,000 行;更多数据请使用 offset,批量下载请使用 REST API。

谁可以调用

没有匿名层级。除本服务说明外,每个端点都需要密钥,而密钥只有在点击发送至账号地址的链接完成确认后才可使用。这对个人只是一次点击;对脚本而言,每要一把密钥就得有一个能收信的邮箱——这正是用意所在。

这与向数据收费无关。数据免费,密钥也免费。这是为了让 API 被我们在出问题时能联系上的人使用,也是为了不让本站沦为一个匿名代理——毕竟我们是代表您接受了各提供方条款的。

限额

默认 60/minute. 每把密钥还带有每月配额,可在您的账号页面查看。若不够用请提出;本平台的意义就在于让您使用这些数据。