# Enerstat OpenAPI / REST API

Enerstat serves real-time and historical energy data for Spain (and other European grids). This document defines the public API endpoints, which are fully accessible without requiring an API key or JWT token.

## Base URL
- Production API: `https://enerstat.io`
- Local Development API: `http://localhost:3000`

---

## Endpoint List

### 1. Get Active Countries
- **Endpoint:** `GET /api/countries`
- **Authentication:** None (Public)
- **Description:** Retrieve a list of countries currently monitored.
- **Response Format:**
  ```json
  [
    {
      "code": "ES",
      "name": "Spain",
      "active": true
    }
  ]
  ```

### 2. Get Available Data Types
- **Endpoint:** `GET /api/data-types`
- **Authentication:** None (Public)
- **Description:** Get the list of active energy data series/metrics available for query.
- **Response Format:**
  ```json
  [
    {
      "code": "day_ahead_prices",
      "name": "Precios mercado diario",
      "unit": "EUR/MWh"
    },
    {
      "code": "total_load",
      "name": "Consumo eléctrico total",
      "unit": "MW"
    },
    {
      "code": "solar_generation",
      "name": "Generación Solar PV",
      "unit": "MW"
    },
    {
      "code": "wind_generation",
      "name": "Generación Eólica",
      "unit": "MW"
    }
  ]
  ```

### 3. Query Energy Data
- **Endpoint:** `GET /api/energy-data/{countryCode}`
- **Authentication:** None (Public)
- **Description:** Query historical energy series for a country using date filtering and aggregation parameters.
- **Path Parameters:**
  - `countryCode`: Use `ES` for Spain.
- **Query Parameters:**
  - `startDate` (string, required): Start date in `YYYY-MM-DD` format (local time).
  - `endDate` (string, required): End date in `YYYY-MM-DD` format (local time).
  - `dataTypes` (string, optional): Comma-separated list of metrics (e.g., `day_ahead_prices,total_load`).
  - `aggregation` (string, optional): Aggregate points. Options: `none`, `hourly`, `daily`.
  - `aggregationFunction` (string, optional): Mathematical aggregation method. Options: `mean`, `sum`, `min`, `max`, `last`. Default: `mean`.
- **Response Format:**
  ```json
  {
    "success": true,
    "data": [
      {
        "timestamp": "2026-06-01T00:00:00.000Z",
        "value": 42.1,
        "unit": "EUR/MWh",
        "dataType": "day_ahead_prices",
        "country": "ES"
      }
    ],
    "metadata": {
      "country": "ES",
      "dataTypes": ["day_ahead_prices"],
      "startDate": "2026-06-01",
      "endDate": "2026-06-02",
      "aggregation": "none",
      "totalPoints": 1
    }
  }
  ```

### 4. Query Specific Series Data
- **Endpoint:** `GET /api/energy-data/{countryCode}/{dataType}`
- **Authentication:** None (Public)
- **Description:** Retrieve points for a single specific data series.
- **Path Parameters:**
  - `countryCode`: `ES` (Spain).
  - `dataType`: e.g. `day_ahead_prices`, `total_load`, `solar_generation`, `wind_generation`.
- **Query Parameters:**
  - Same as standard query (`startDate`, `endDate`, `aggregation`, `aggregationFunction`).
- **Response Format:**
  Similar to main query, returning filtered series only.

### 5. Get Real-Time / Latest 24 Hours Data
- **Endpoint:** `GET /api/energy-data/{countryCode}/latest`
- **Authentication:** None (Public)
- **Description:** Fetch all data points compiled in the last 24 hours.
- **Response Format:**
  ```json
  {
    "success": true,
    "data": [...],
    "metadata": {
      "country": "ES",
      "period": "last_24_hours",
      "totalPoints": 96
    }
  }
  ```

---

## Interactive Swagger Playground
For visual testing, schema details, and testing queries dynamically, visit the Swagger UI dashboard at:
`/api/docs` on the host running the backend server.