GEFRI API documentation

The Global Education Futures Readiness Index (GEFRI) API provides open access to country-level and global summary data, enabling researchers, developers, and policymakers to analyze, compare, and download up-to-date GEFRI results. The API is public and requires no authentication.

Version: 1.0   |   Format: JSON

Quick start: Example queries

• Get all countries (global summary):

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

• Get Aruba's full profile (by ISO3 code):

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

• Get multiple countries by code:

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

• Get all countries in Latin America & Caribbean, sorted by score (descending):

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

• Return only selected fields (country code and composite score):

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

• Return only specific indicators for a country:

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

• Fetch a historical snapshot (December of a given year):

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

Basic usage & query parameters

• All countries (default):
  /api/gefri
• Single country by ISO3 code:
  /api/gefri?code=FIN
• Multiple countries by ISO3 code:
  /api/gefri?codes=FIN,USA,BRA
• By region (case-insensitive, supports aliases like "LAC", "EAP"):
  /api/gefri?region=lac
• Sort results (default is descending for numbers):
  /api/gefri?sort=score&order=asc
• Return specific top-level fields only:
  /api/gefri?fields=country name,score,region
• Get aliased fields (shortnames):
  /api/gefri?shortnames=true
• Select a historical snapshot (December of a given year):
  /api/gefri?year=2023

  Historical archives are stored by month. Specify the year to retrieve the December snapshot for that year; the API returns 404 if the archive is unavailable.

Country-level indicators

• Filter indicator details (by code, comma-separated, case-insensitive):
  /api/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details array is included only in country-level results.

Sorting

• Sort by any field:
  /api/gefri?sort=score&order=desc
• Sort ascending:
  /api/gefri?sort=score&order=asc
• Sort alphabetically:
  /api/gefri?sort=Country Name&order=asc

Response structure & error handling

{
  "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 Handling: If a request is invalid, the response includes an "error" key with a descriptive message. For example:
{ "error": "Country code not found" }

Data dictionary

Each object in the GEFRI API includes the following fields. Field availability may vary. All scores are normalized on a 0–100 scale unless otherwise noted. Population, total is used only as an auxiliary series (for microstate flags and per-million transformations); it does not enter any GEFRI scores.

indicator_details (array, per-country only): Each object contains:

Notes:
- indicator_details only appears in per-country API results.
- data_source is always included for traceability.
- Percentiles are returned as ordinal strings ("84th", "63rd"), not numbers.

Supported aliases

Use these aliases for convenience in your queries.

Notes and attribution

• Data is updated monthly. Indicators are sourced from open data (primarily World Bank Open Data).
• Please cite Education Futures and link to https://gefri.educationfutures.com when using GEFRI in research or applications.
• For feedback or collaboration, contact us.