GEFRI API 文档

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

版本: 1.0   |   格式: JSON

快速开始：示例查询

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

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

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

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

• 按代码获取多个国家：

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

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

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

• 仅返回指定字段（国家代码和综合得分）：

  curl "https://gefri.educationfutures.com/api/gefri?fields=country code,score"

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

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

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

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

基本用法和查询参数

• 全部国家（默认）：
  /api/gefri
• 按 ISO3 代码获取单个国家：
  /api/gefri?code=FIN
• 按 ISO3 代码获取多个国家：
  /api/gefri?codes=FIN,USA,BRA
• 按地区（不区分大小写，支持如 “LAC”“EAP” 等别名）：
  /api/gefri?region=lac
• 按结果排序（数值默认降序）：
  /api/gefri?sort=score&order=asc
• 仅返回指定顶层字段：
  /api/gefri?fields=country name,score,region
• 获取别名字段（shortnames）：
  /api/gefri?shortnames=true
• 选择历史快照（指定年份 12 月）：
  /api/gefri?year=2023

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

国家层级指标

• 筛选指标详情（按代码，逗号分隔，不区分大小写）：
  /api/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details 数组仅包含在国家层级结果中。

排序

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

响应结构与错误处理

{
  "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 键。例如：
{ "error": "Country code not found" }

数据字典

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

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

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

支持的别名

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

说明与署名

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