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: v1   |   Format: JSON

Quick start: Example queries

• Get all countries (global summary):

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

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

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

• Get multiple countries by code:

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

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

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

• Return only selected top-level fields:

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

• Return only specific indicators for a country:

  curl "https://gefri.educationfutures.com/api/v1/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/v1/gefri?year=2023&codes=FIN,SWE"

Basic usage & query parameters

• All countries (default):
  /api/v1/gefri
• Single country by ISO3 code (code also accepts comma-separated ISO3 values):
  /api/v1/gefri?code=FIN
• Multiple countries by ISO3 code (codes takes precedence over code):
  /api/v1/gefri?codes=FIN,USA,BRA
• By region (case-insensitive, supports aliases like "LAC", "EAP"):
  /api/v1/gefri?region=lac
• Sort results (default is descending for numbers):
  /api/v1/gefri?sort=score&order=asc
• Return specific top-level fields only (matched case-insensitively by actual field name):
  /api/v1/gefri?fields=Country Name,Country Code,Region
• Add aliased fields (shortnames) without removing the long field names:
  /api/v1/gefri?shortnames=true
• Select a historical snapshot (December of a given year):
  /api/v1/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.

Behavior notes

• If code or codes is supplied, country mode takes precedence even when level is omitted or set to global. level=country without country codes is invalid.
• Both code and codes accept comma-separated ISO3 values. When both are present, codes takes precedence.
• shortnames=true adds RegionShort plus short component aliases such as score, access, innovation, human, governance, and infra.
• Field filtering matches top-level keys case-insensitively and retains indicator_details when that array is present.
• All response keys ending with confidence are removed recursively before the payload is returned.

Country-level indicators

• Filter indicator details (by code, comma-separated, case-insensitive):
  /api/v1/gefri?code=ABW&indicators=SE.SEC.UNER.LO.ZS,EG.ELC.ACCS.ZS
• indicator_details appears only in country-level results and is retained even when fields filtering is applied.

Sorting

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

Response structure & error handling

{
  "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 handling: If a request is invalid, the response includes an error key with a descriptive message. For example:
{ "apiVersion": "1", "error": "Invalid request." }

When exactly one country matches, data is returned as an object. When multiple countries match, data is returned as an array. Missing country files are skipped, so unmatched codes can return count 0 instead of 404.

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). World Bank Open Data.
• When using GEFRI in research or applications, please cite Education Futures.
• For feedback or collaboration, contact us. contact.