{
  "openapi": "3.0.3",
  "info": {
    "title": "EuroData API",
    "description": "Aggregated European statistical data from Eurostat, ECB, and World Bank. 20 endpoints covering GDP, inflation, government debt, CO₂ emissions, R&D expenditure and more for all 27 EU member states.",
    "version": "1.0.0",
    "contact": { "url": "https://github.com/RishikeshGovind/eurodata-api" },
    "license": { "name": "Data: CC BY 4.0 (World Bank) / OGL v3 (Eurostat)", "url": "https://ec.europa.eu/eurostat/about-eurostat/policies/copyright" }
  },
  "servers": [{ "url": "https://eurodata-api.up.railway.app", "description": "Production" }],
  "tags": [
    { "name": "Economy",        "description": "GDP, inflation, trade, government finance" },
    { "name": "Labour",         "description": "Unemployment statistics" },
    { "name": "Demographics",   "description": "Population data" },
    { "name": "Finance",        "description": "ECB interest rates" },
    { "name": "Environment",    "description": "Energy and CO₂ emissions" },
    { "name": "Social",         "description": "Health and education" },
    { "name": "Premium",        "description": "Cross-country analysis: compare, rankings, trends, snapshot" },
    { "name": "Reference",      "description": "Countries list and metadata" }
  ],
  "paths": {
    "/api/gdp": {
      "get": {
        "tags": ["Economy"],
        "summary": "GDP at market prices",
        "description": "Gross Domestic Product at market prices in million EUR (current prices) for one or all EU-27 countries. Sourced from Eurostat dataset `nama_10_gdp`.",
        "operationId": "getGDP",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "format", "in": "query", "description": "Frequency — `annual` (default) or `quarterly`", "schema": { "type": "string", "enum": ["annual", "quarterly"] } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/inflation": {
      "get": {
        "tags": ["Economy"],
        "summary": "HICP inflation rate",
        "description": "Harmonised Index of Consumer Prices — annual average rate of change (%). Sourced from Eurostat dataset `prc_hicp_aind`.",
        "operationId": "getInflation",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/unemployment": {
      "get": {
        "tags": ["Labour"],
        "summary": "Unemployment rate",
        "description": "Unemployment rate as % of active population. Sourced from Eurostat dataset `une_rt_a`.",
        "operationId": "getUnemployment",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "age_group", "in": "query", "description": "Age group filter", "schema": { "type": "string", "enum": ["youth", "adult", "total"], "default": "total" } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/population": {
      "get": {
        "tags": ["Demographics"],
        "summary": "Population on 1 January",
        "description": "Total population on 1 January with year-over-year growth rate automatically calculated. Sourced from Eurostat dataset `demo_pjan`.",
        "operationId": "getPopulation",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/interest-rates": {
      "get": {
        "tags": ["Finance"],
        "summary": "ECB key interest rates",
        "description": "European Central Bank key interest rates — main refinancing rate, deposit facility rate, and marginal lending facility rate.",
        "operationId": "getInterestRates",
        "parameters": [
          { "name": "type", "in": "query", "description": "Rate type", "schema": { "type": "string", "enum": ["main", "deposit", "lending"] } },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/trade": {
      "get": {
        "tags": ["Economy"],
        "summary": "Trade statistics (% of GDP)",
        "description": "Trade in goods and services as % of GDP — exports, imports, balance, or total. Sourced from World Bank.",
        "operationId": "getTrade",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "type", "in": "query", "description": "Trade type", "schema": { "type": "string", "enum": ["imports", "exports", "balance", "total"] } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/government-debt": {
      "get": {
        "tags": ["Economy"],
        "summary": "Government gross debt (% of GDP)",
        "description": "General government consolidated gross debt as % of GDP — the Maastricht criterion. The EU threshold is 60%. Sourced from Eurostat dataset `gov_10dd_edpt1`.",
        "operationId": "getGovernmentDebt",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/government-deficit": {
      "get": {
        "tags": ["Economy"],
        "summary": "Government deficit/surplus (% of GDP)",
        "description": "General government net lending (+) / net borrowing (-) as % of GDP. Negative values indicate a deficit. The Maastricht threshold is −3%. Sourced from Eurostat dataset `gov_10dd_edpt1`.",
        "operationId": "getGovernmentDeficit",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/rd-expenditure": {
      "get": {
        "tags": ["Economy"],
        "summary": "R&D expenditure (% of GDP)",
        "description": "Gross domestic expenditure on R&D (GERD) as % of GDP. The EU Barcelona objective is 3% of GDP. Filter by performing sector. Sourced from Eurostat dataset `rd_e_gerdtot`.",
        "operationId": "getRDExpenditure",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "sector", "in": "query", "description": "Performing sector", "schema": { "type": "string", "enum": ["total", "business", "government", "higher_education"], "default": "total" } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/current-account": {
      "get": {
        "tags": ["Economy"],
        "summary": "Current account balance (% of GDP)",
        "description": "Current account balance as % of GDP. Positive = surplus, negative = deficit. Sourced from World Bank indicator `BN.CAB.XOKA.GD.ZS`.",
        "operationId": "getCurrentAccount",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/fdi": {
      "get": {
        "tags": ["Economy"],
        "summary": "FDI net inflows (% of GDP)",
        "description": "Foreign direct investment net inflows as % of GDP. Sourced from World Bank indicator `BX.KLT.DINV.WD.GD.ZS`.",
        "operationId": "getFDI",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/co2": {
      "get": {
        "tags": ["Environment"],
        "summary": "CO₂ emissions per capita",
        "description": "Carbon dioxide emissions per capita in metric tons, excluding land use change. Sourced from World Bank indicator `EN.GHG.CO2.PC.CE.AR5`.",
        "operationId": "getCO2",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["Social"],
        "summary": "Health statistics",
        "description": "Health indicators — life expectancy at birth, hospital beds per 100k, or physicians per 1,000 population.",
        "operationId": "getHealth",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "indicator", "in": "query", "description": "Health indicator", "schema": { "type": "string", "enum": ["life_expectancy", "hospital_beds", "doctors_per_1000"], "default": "life_expectancy" } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/education": {
      "get": {
        "tags": ["Social"],
        "summary": "Education enrollment",
        "description": "Student enrollment by ISCED education level. Sourced from Eurostat dataset `educ_uoe_enra01`.",
        "operationId": "getEducation",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "level", "in": "query", "description": "Education level", "schema": { "type": "string", "enum": ["primary", "secondary", "tertiary"] } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/energy": {
      "get": {
        "tags": ["Environment"],
        "summary": "Energy primary production (KTOE)",
        "description": "Primary energy production in thousand tonnes of oil equivalent (KTOE) by source. Sourced from Eurostat dataset `nrg_bal_s`.",
        "operationId": "getEnergy",
        "parameters": [
          { "$ref": "#/components/parameters/country" },
          { "$ref": "#/components/parameters/year" },
          { "name": "type", "in": "query", "description": "Energy source", "schema": { "type": "string", "enum": ["renewable", "fossil", "nuclear"] } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/countries": {
      "get": {
        "tags": ["Reference"],
        "summary": "All EU-27 member states",
        "description": "All 27 EU member states (post-Brexit) with ISO-2 and ISO-3 codes, capitals, currencies, population estimates, and EU accession year.",
        "operationId": "getCountries",
        "parameters": [{ "$ref": "#/components/parameters/csvFormat" }],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" } }
      }
    },
    "/api/compare": {
      "get": {
        "tags": ["Premium"],
        "summary": "Compare countries side-by-side",
        "description": "Compare up to 10 EU countries for any of the 13 supported indicators. Returns both a pivot table (year → country values) and a flat records array for CSV export.",
        "operationId": "compareCountries",
        "parameters": [
          { "name": "countries", "in": "query", "required": true, "description": "Comma-separated ISO-2 country codes (2–10 countries)", "example": "DE,FR,IT", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/indicator" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/rankings": {
      "get": {
        "tags": ["Premium"],
        "summary": "EU-27 ranked by indicator",
        "description": "All 27 EU member states ranked highest to lowest for any supported indicator and year, with rank numbers included.",
        "operationId": "getRankings",
        "parameters": [
          { "$ref": "#/components/parameters/indicator" },
          { "$ref": "#/components/parameters/year" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/trends": {
      "get": {
        "tags": ["Premium"],
        "summary": "Historical trend series",
        "description": "Full historical data series for one country and indicator. Returns year-over-year absolute and % change, 5-year rolling average, and a summary object with min/max/mean/total change.",
        "operationId": "getTrends",
        "parameters": [
          { "name": "country", "in": "query", "required": true, "description": "ISO-2 country code", "example": "DE", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } },
          { "$ref": "#/components/parameters/indicator" },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" } }
      }
    },
    "/api/snapshot/{country}": {
      "get": {
        "tags": ["Premium"],
        "summary": "Full country snapshot",
        "description": "All 13 key indicators for one country in a single API call — GDP, inflation, unemployment, population, trade balance, life expectancy, energy, government debt, deficit, current account, FDI, R&D, and CO₂.",
        "operationId": "getSnapshot",
        "parameters": [
          { "name": "country", "in": "path", "required": true, "description": "ISO-2 country code", "example": "DE", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" } },
          { "$ref": "#/components/parameters/csvFormat" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/SuccessArray" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    }
  },
  "components": {
    "parameters": {
      "country": {
        "name": "country", "in": "query",
        "description": "ISO 3166-1 alpha-2 country code for an EU-27 member state. Omit to return all 27 countries.",
        "example": "DE",
        "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "DE" }
      },
      "year": {
        "name": "year", "in": "query",
        "description": "Four-digit year. Omit for all available years.",
        "example": 2023,
        "schema": { "type": "integer", "minimum": 1960, "maximum": 2026 }
      },
      "indicator": {
        "name": "indicator", "in": "query", "required": true,
        "description": "Indicator key",
        "schema": {
          "type": "string",
          "enum": ["gdp","inflation","unemployment","population","trade_balance","life_expectancy","energy_renewable","government_debt","government_deficit","current_account","fdi_inflows","rd_expenditure","co2_emissions"]
        }
      },
      "csvFormat": {
        "name": "format", "in": "query",
        "description": "Set to `csv` to receive a downloadable CSV file instead of JSON.",
        "schema": { "type": "string", "enum": ["csv"] }
      }
    },
    "responses": {
      "SuccessArray": {
        "description": "Successful response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "success":          { "type": "boolean", "example": true },
                "source":           { "type": "string",  "example": "Eurostat" },
                "attribution":      { "type": "string" },
                "cached":           { "type": "boolean" },
                "cache_expires_at": { "type": "string", "format": "date-time" },
                "data": {
                  "type": "object",
                  "properties": {
                    "indicator": { "type": "string" },
                    "count":     { "type": "integer" },
                    "records":   { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }
                  }
                }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid parameter",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Record": {
        "type": "object",
        "properties": {
          "country":      { "type": "string",  "example": "Germany" },
          "country_code": { "type": "string",  "example": "DE" },
          "year":         { "type": "string",  "example": "2023" },
          "value":        { "type": "number",  "example": 62.3 },
          "unit":         { "type": "string",  "example": "% of GDP" },
          "source":       { "type": "string",  "example": "Eurostat" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": {
            "type": "object",
            "properties": {
              "code":    { "type": "integer", "example": 400 },
              "message": { "type": "string",  "example": "Invalid country code." }
            }
          }
        }
      }
    }
  }
}