{
  "openapi": "3.1.0",
  "info": {
    "title": "WorldJobsData API",
    "version": "1.0.0",
    "description": "Free, no-auth JSON API for AI job risk data across 206 countries. Built on ILO ILOSTAT (CC BY 4.0), UNDP Human Development Report (CC BY 3.0 IGO), and World Bank Open Data (CC BY 4.0). No API key required. CORS open.",
    "contact": {
      "name": "WorldJobsData",
      "url": "https://www.worldjobsdata.com/api"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://www.worldjobsdata.com",
      "description": "Production (CDN-cached via Vercel)"
    }
  ],
  "paths": {
    "/data/meta.json": {
      "get": {
        "operationId": "getCountryList",
        "summary": "Country list and summary scores",
        "description": "Returns all 206 countries with their weighted AI exposure, robotics risk, offshoring risk, WFH potential scores, employment totals, and risk velocity metadata. Use this to build country pickers or summary tables without fetching individual country files.",
        "responses": {
          "200": {
            "description": "Country list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetaResponse"
                }
              }
            }
          }
        }
      }
    },
    "/data/countries/{code}.json": {
      "get": {
        "operationId": "getCountryData",
        "summary": "Full country data",
        "description": "Returns complete AI job risk data for one country: occupation breakdown by ISCO-08 major group, individual AI scores, employment figures, wages (where available), World Bank economy indicators, and UNDP Human Development Index data.",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "ISO 3166-1 alpha-2 country code in lowercase (e.g. us, de, in). All 206 country files use lowercase codes.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "pattern": "^[a-z]{2}$",
              "example": "us"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Country data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CountryData"
                }
              }
            }
          },
          "404": {
            "description": "Country code not found"
          }
        }
      }
    },
    "/data/isco_scores.json": {
      "get": {
        "operationId": "getIscoScores",
        "summary": "ISCO-08 occupation scores",
        "description": "Returns AI exposure, robotics risk, offshoring risk, and WFH potential scores for every ISCO-08 occupation code (major groups 0-9 and sub-major groups 01-96). Includes rationale text for each score. These scores are applied uniformly across countries based on published task-automation research.",
        "responses": {
          "200": {
            "description": "ISCO scores map keyed by ISCO code string",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IscoScoresResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MetaResponse": {
        "type": "object",
        "properties": {
          "countries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CountrySummary"
            }
          },
          "generated_by": {
            "type": "string"
          },
          "tier_counts": {
            "type": "object",
            "description": "Count of countries at each data quality tier (A, B, C)"
          }
        }
      },
      "CountrySummary": {
        "type": "object",
        "description": "Summary scores for one country as returned by /data/meta.json",
        "properties": {
          "code": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 code, uppercase (e.g. US)"
          },
          "name": {
            "type": "string",
            "description": "Country name in English"
          },
          "tier": {
            "type": "string",
            "enum": ["A", "B", "C"],
            "description": "Data quality tier. A=full BLS/Eurostat detail with wages. B=occupation groups, limited wages. C=ILO ILOSTAT major groups only."
          },
          "weighted_ai_exposure": {
            "type": "number",
            "description": "Workforce-weighted AI exposure score (0-10). Weighted average of ISCO major group AI scores by employment share."
          },
          "weighted_robotics_risk": {
            "type": "number",
            "description": "Workforce-weighted robotics risk score (0-10)"
          },
          "weighted_offshoring_risk": {
            "type": "number",
            "description": "Workforce-weighted offshoring risk score (0-10)"
          },
          "weighted_wfh_potential": {
            "type": "number",
            "description": "Workforce-weighted work-from-home potential score (0-10)"
          },
          "total_employment_thousands": {
            "type": "number",
            "description": "Total employment in thousands"
          },
          "risk_velocity": {
            "type": "number",
            "description": "AI disruption speed score (0-10). How quickly AI is likely to reshape this workforce."
          },
          "risk_velocity_label": {
            "type": "string",
            "description": "Human-readable disruption timeline label"
          },
          "recovery_resilience": {
            "type": "number",
            "description": "Worker recovery resilience score (0-10). Capacity to adapt to AI displacement via retraining, labour market flexibility, and social support."
          },
          "has_wages": {
            "type": "boolean",
            "description": "Whether wage data is available for this country"
          },
          "year": {
            "type": "integer",
            "description": "Reference year of employment data"
          },
          "source": {
            "type": "string",
            "description": "Primary data source name"
          },
          "wb_data_available": {
            "type": "boolean",
            "description": "Whether World Bank economy indicators are available"
          },
          "youth_unemployment_rate": {
            "type": ["number", "null"],
            "description": "Youth unemployment rate (%)"
          },
          "female_labor_force_pct": {
            "type": ["number", "null"],
            "description": "Female share of labour force (%)"
          }
        }
      },
      "CountryData": {
        "type": "object",
        "description": "Full country data as returned by /data/countries/{code}.json",
        "properties": {
          "country_code": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 code, uppercase"
          },
          "country_name": {
            "type": "string"
          },
          "year": {
            "type": "integer",
            "description": "Reference year of employment data"
          },
          "tier": {
            "type": "string",
            "enum": ["A", "B", "C"]
          },
          "total_employment_thousands": {
            "type": ["number", "null"]
          },
          "risk_velocity": {
            "type": ["number", "null"]
          },
          "risk_velocity_label": {
            "type": ["string", "null"]
          },
          "recovery_resilience": {
            "type": ["number", "null"]
          },
          "recovery_resilience_label": {
            "type": ["string", "null"]
          },
          "demographic_alignment": {
            "type": ["string", "null"],
            "description": "Whether demographic trends amplify or dampen AI risk (bullish/bearish/neutral)"
          },
          "sovereign_buffer": {
            "type": ["number", "null"],
            "description": "Sovereign wealth buffer score (0-10)"
          },
          "occupations": {
            "type": "array",
            "description": "ISCO-08 major group occupation breakdown",
            "items": {
              "$ref": "#/components/schemas/Occupation"
            }
          },
          "wb_economy": {
            "$ref": "#/components/schemas/WbEconomy"
          },
          "hdr_data": {
            "$ref": "#/components/schemas/HdrData"
          }
        }
      },
      "Occupation": {
        "type": "object",
        "description": "One ISCO-08 major group occupation entry",
        "properties": {
          "isco_code": {
            "type": "string",
            "description": "ISCO-08 major group code as string (0-9)"
          },
          "label": {
            "type": "string",
            "description": "Occupation group name"
          },
          "employment_thousands": {
            "type": ["number", "null"],
            "description": "Employment in thousands"
          },
          "employment_pct": {
            "type": ["number", "null"],
            "description": "Share of total employment (%)"
          },
          "female_share_pct": {
            "type": ["number", "null"],
            "description": "Female share of this occupation group (%)"
          },
          "median_annual_wage_usd": {
            "type": ["number", "null"],
            "description": "Median annual wage in USD. Null if not available for this country."
          },
          "wage_year": {
            "type": ["integer", "null"],
            "description": "Reference year for wage data"
          },
          "ai_exposure": {
            "type": ["number", "null"],
            "description": "AI exposure score (0-10) for this occupation group"
          },
          "robotics_risk": {
            "type": ["number", "null"],
            "description": "Robotics risk score (0-10)"
          },
          "offshoring_risk": {
            "type": ["number", "null"],
            "description": "Offshoring risk score (0-10)"
          },
          "wfh_potential": {
            "type": ["number", "null"],
            "description": "Work-from-home potential score (0-10)"
          }
        }
      },
      "WbEconomy": {
        "type": "object",
        "description": "World Bank economy indicators (CC BY 4.0). Most recent available year per indicator. Null if not available.",
        "properties": {
          "gdp_per_capita_usd": {
            "type": ["number", "null"]
          },
          "gdp_per_capita_usd_year": {
            "type": ["integer", "null"]
          },
          "population": {
            "type": ["number", "null"]
          },
          "population_year": {
            "type": ["integer", "null"]
          },
          "labor_force_participation_pct": {
            "type": ["number", "null"]
          },
          "labor_force_participation_pct_year": {
            "type": ["integer", "null"]
          },
          "labor_force_participation_female_pct": {
            "type": ["number", "null"]
          },
          "unemployment_pct": {
            "type": ["number", "null"]
          },
          "unemployment_pct_year": {
            "type": ["integer", "null"]
          },
          "poverty_headcount_3usd_pct": {
            "type": ["number", "null"]
          },
          "poverty_headcount_3usd_pct_year": {
            "type": ["integer", "null"]
          },
          "gini": {
            "type": ["number", "null"],
            "description": "Gini inequality coefficient. Higher = more unequal."
          },
          "gini_year": {
            "type": ["integer", "null"]
          },
          "adult_literacy_pct": {
            "type": ["number", "null"]
          },
          "adult_literacy_pct_year": {
            "type": ["integer", "null"]
          },
          "life_expectancy": {
            "type": ["number", "null"]
          },
          "life_expectancy_year": {
            "type": ["integer", "null"]
          }
        }
      },
      "HdrData": {
        "type": "object",
        "description": "UNDP Human Development Report indicators (CC BY 3.0 IGO). Null if country not in UNDP dataset.",
        "properties": {
          "hdi": {
            "type": ["number", "null"],
            "description": "Human Development Index (0-1). Tiers: >=0.8 Very High, >=0.7 High, >=0.55 Medium, <0.55 Low."
          },
          "hdi_rank": {
            "type": ["integer", "null"],
            "description": "Global HDI rank (1 = highest)"
          },
          "life_expectancy": {
            "type": ["number", "null"],
            "description": "Life expectancy at birth (years)"
          },
          "expected_years_schooling": {
            "type": ["number", "null"],
            "description": "Expected years of schooling for children entering school today"
          },
          "mean_years_schooling": {
            "type": ["number", "null"],
            "description": "Mean years of schooling for adults aged 25+"
          },
          "gni_per_capita_ppp": {
            "type": ["number", "null"],
            "description": "Gross National Income per capita in PPP international dollars"
          },
          "hdr_year": {
            "type": ["integer", "string", "null"],
            "description": "Reference year of HDR data (e.g. 2022 or 2023/24)"
          }
        }
      },
      "IscoScoresResponse": {
        "type": "object",
        "description": "Map of ISCO code strings to score objects. Keys include major groups (0-9) and sub-major groups (01-96).",
        "additionalProperties": {
          "$ref": "#/components/schemas/IscoScore"
        }
      },
      "IscoScore": {
        "type": "object",
        "properties": {
          "digital_ai_exposure": {
            "type": "number",
            "description": "AI exposure score (0-10) for this occupation code"
          },
          "robotics_risk": {
            "type": "number",
            "description": "Robotics risk score (0-10)"
          },
          "offshoring_risk": {
            "type": "number",
            "description": "Offshoring risk score (0-10)"
          },
          "wfh_potential": {
            "type": "number",
            "description": "Work-from-home potential score (0-10)"
          },
          "ai_rationale": {
            "type": "string",
            "description": "Plain-text explanation of the AI exposure score"
          },
          "robotics_rationale": {
            "type": "string",
            "description": "Plain-text explanation of the robotics risk score"
          }
        }
      }
    }
  }
}