GEFRI API 文档

全球教育未来准备指数（GEFRI）API 提供对国家层级和全球汇总数据的开放访问，使研究人员、开发者和政策制定者能够分析、比较并下载最新 GEFRI 结果。API 公开且无需认证。

版本: v1   |   格式: JSON

快速开始：示例查询

• 获取全部国家（全球汇总）：

  curl https://gefri.educationfutures.com/api/v1/gefri

• 获取 Aruba 的完整概览（按 ISO3 代码）：

  curl https://gefri.educationfutures.com/api/v1/gefri?code=ABW

• 按代码获取多个国家：

  curl "https://gefri.educationfutures.com/api/v1/gefri?codes=USA,FIN,BRA"

• 获取拉丁美洲和加勒比地区所有国家，并按得分降序排序：

  curl "https://gefri.educationfutures.com/api/v1/gefri?region=lac&sort=score&order=desc"

• 仅返回指定的顶层字段：

  curl "https://gefri.educationfutures.com/api/v1/gefri?fields=Country Code,Country Name,Composite GEFRI Score"

• 仅返回某个国家的指定指标：

  curl "https://gefri.educationfutures.com/api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS"

• 获取历史快照（指定年份 12 月）：

  curl "https://gefri.educationfutures.com/api/v1/gefri?year=2023&codes=FIN,SWE"

基本用法和查询参数

• 全部国家（默认）：
  /api/v1/gefri
• 按 ISO3 代码获取单个国家（code 也接受逗号分隔的多个 ISO3 值）：
  /api/v1/gefri?code=FIN
• 按 ISO3 代码获取多个国家（codes 的优先级高于 code）：
  /api/v1/gefri?codes=FIN,USA,BRA
• 按地区（不区分大小写，支持如 “LAC”“EAP” 等别名）：
  /api/v1/gefri?region=lac
• 按结果排序（数值默认降序）：
  /api/v1/gefri?sort=score&order=asc
• 仅返回指定的顶层字段（按实际字段名不区分大小写匹配）：
  /api/v1/gefri?fields=Country Name,Country Code,Region
• 添加别名字段（shortnames），但不移除原始长字段名：
  /api/v1/gefri?shortnames=true
• 选择历史快照（指定年份 12 月）：
  /api/v1/gefri?year=2023

  历史归档按月份存储。指定年份将返回该年份 12 月的快照；如果归档不可用，API 返回 404。

行为说明

• 如果提供了 code 或 codes，则 country 模式优先，即使省略 level 或将其设置为 global 也是如此。没有国家代码时使用 level=country 属于无效请求。
• code 和 codes 都接受逗号分隔的 ISO3 值。当两者同时出现时，codes 优先。
• shortnames=true 会添加 RegionShort 以及 score、access、innovation、human、governance、infra 等简写字段。
• fields 过滤按顶层键名进行不区分大小写匹配，并在 indicator_details 数组存在时保留该字段。
• 所有以 confidence 结尾的响应键都会在返回前被递归移除。

国家层级指标

• 筛选指标详情（按代码，逗号分隔，不区分大小写）：
  /api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details 仅出现在国家层级结果中，并且即使应用 fields 过滤也会被保留。

排序

• 可按任意字段排序：
  /api/v1/gefri?sort=score&order=desc
• 升序排序：
  /api/v1/gefri?sort=score&order=asc
• 按字母顺序排序：
  /api/v1/gefri?sort=Country Name&order=asc

响应结构与错误处理

{
  "apiVersion": "1",
  "level": "country",
  "snapshot": "current",
  "count": 1,
  "data": {
    "Country Name": "Aruba",
    "Country Code": "ABW",
    "Region": "Latin America & Caribbean",
    "Composite GEFRI Score": 67.8,
    // ...other fields...
    "indicator_details": [
      {
        "indicator_code": "SP.POP.TOTL",
        "indicator_name": "Population, total",
        "component": null,
        "year": 2023,
        "reported_value": 41454761,
        "data_source": "World Bank",
        "normalized_value": null,
        "global_percentile": null,
        "regional_percentile": null,
        "notes": ""
      }
      // ...etc...
    ]
  }
}

错误处理： 如果请求无效，响应会包含带有描述性信息的 error 键。例如：
{ "apiVersion": "1", "error": "Invalid request." }

当恰好匹配一个国家时，data 返回对象；当匹配多个国家时，data 返回数组。缺失的国家文件会被跳过，因此未匹配的代码可能返回 count 0，而不是 404。

数据字典

GEFRI API 中的每个对象都包含以下字段。字段是否可用可能不同。除非另有说明，所有得分都标准化为 0–100。Population, total 仅用作辅助序列（用于微型国家标记和每百万转换），不计入任何 GEFRI 得分。

indicator_details（数组，仅国家层级）：每个对象包含：

说明：
- indicator_details 仅出现在单个国家 API 结果中。
- 为保证可追溯性，data_source 始终包含在内。
- Percentile 以序数字符串返回（如“84th”“63rd”），而不是数字。

支持的别名

在查询中可使用以下别名以提高便利性。

说明与署名

• 数据每月更新。指标来源于开放数据（主要为世界银行开放数据）。 World Bank Open Data.
• 在研究或应用中使用 GEFRI 时，请引用 Education Futures.
• 如有反馈或合作意向，请联系我们。 联系.