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/datasets | catalog:read | 目录,含针对每个数据集的访问判定 |
| GET /api/v1/datasets/<slug> | catalog:read | 单个数据集及其指标与新鲜度 |
| GET /api/v1/areas | catalog:read | 带 ISO 代码的地理单元 |
| GET /api/v1/observations | data:read | 数据本身。受许可管控。 |
| GET /api/v1/search | catalog:read | 与查询匹配的问题、数据集、指标与地区 |
| GET /api/v1/freshness | catalog:read | 每个数据集上次刷新的时间及其是否已过期 |
| GET /api/v1/publications | catalog:read | 如何引用 Mondo,以及其背后的研究 |
查询观测值
| 参数 | 示例 | 备注 |
|---|---|---|
| dataset | wb-trade-openness | 短标识。此项与 indicator 必须提供其一。 |
| indicator | NE.TRD.GNFS.ZS,NE.EXP.GNFS.ZS | 以逗号分隔的来源代码 |
| area | CAN,FRA,JPN,CHN | ISO-3、ISO-2、NUTS 或汇总代码 |
| partner | USA | 仅适用于双边序列 |
| start / end | 2000 / 2024 | 年份,含首尾 |
| use | commercial | 本次请求所声明的用途;必须为许可所允许 |
| limit / offset | 5000 / 0 | 上限 50000 |
| lang | fr | en, 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. 每把密钥还带有每月配额,可在您的账号页面查看。若不够用请提出;本平台的意义就在于让您使用这些数据。