> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexenergie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /market/fundamentals — ENTSO-E Power System Data

> Retrieve the ENTSO-E power-system fundamentals currently used by Nexenergie models: load forecasts, generation mix, and cross-border flows.

The `GET /market/fundamentals` endpoint returns the current ENTSO-E power-system data that feeds the Nexenergie forecast models: total load forecast, generation by fuel type, and cross-border interconnection flows. This data is sourced directly from ENTSO-E's Transparency Platform and is updated multiple times daily as new snapshots are published, ensuring the data returned here always reflects the most recent available values.

## Endpoint

| Method | Path                          | Auth     |
| ------ | ----------------------------- | -------- |
| `GET`  | `/api/v1/market/fundamentals` | Required |

## Query Parameters

<ParamField query="date" type="string" required>
  The date for which to retrieve power-system fundamentals. Format: `YYYY-MM-DD`. Data is available for past dates as well as the current day and near-term future dates when ENTSO-E forecasts are published.
</ParamField>

<ParamField query="hour" type="integer">
  Filter the response to a single hour of the day. Accepts integers from `0` (midnight) to `23` (11 PM). When omitted, all 24 hourly records for the requested date are returned.
</ParamField>

## Request Example

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.nexenergie.ai/api/v1/market/fundamentals" \
    --header "Authorization: Bearer <token>" \
    --data-urlencode "date=2024-06-15"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.nexenergie.ai/api/v1/market/fundamentals"
  headers = {"Authorization": "Bearer <token>"}
  params = {
      "date": "2024-06-15",
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()

  print(f"Data as of: {data['data_as_of']}")
  for hour in data["hours"]:
      renewables = hour["generation"]["wind_mw"] + hour["generation"]["solar_mw"]
      print(
          f"H{hour['hour']:02d}  Load: {hour['total_load_mw']} MW  "
          f"Renewables: {renewables} MW  "
          f"Net flow: {hour['cross_border_flows_mw']} MW"
      )
  ```
</CodeGroup>

## Response

A successful request returns HTTP `200 OK` with a JSON object containing hourly fundamentals for the requested date.

<ResponseField name="date" type="string">
  The date for which fundamentals are returned. Format: `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="data_as_of" type="string">
  ISO 8601 timestamp indicating when ENTSO-E last published the data included in this response. Reflects the freshness of the underlying ENTSO-E snapshot.
</ResponseField>

<ResponseField name="hours" type="array">
  Array of hourly power-system fundamental records for the requested date.

  <Expandable title="hours items">
    <ResponseField name="hour" type="integer">
      Hour of the day (0–23) to which this record applies.
    </ResponseField>

    <ResponseField name="total_load_mw" type="number">
      Total forecast system load for the Spanish bidding zone in megawatts (MW), as published by ENTSO-E.
    </ResponseField>

    <ResponseField name="generation" type="object">
      Breakdown of scheduled or forecast generation by fuel type, all values in MW.

      <Expandable title="generation fields">
        <ResponseField name="wind_mw" type="number">
          Wind generation (onshore and offshore combined) in MW.
        </ResponseField>

        <ResponseField name="solar_mw" type="number">
          Solar photovoltaic generation in MW.
        </ResponseField>

        <ResponseField name="hydro_mw" type="number">
          Hydro generation (run-of-river and reservoir) in MW.
        </ResponseField>

        <ResponseField name="nuclear_mw" type="number">
          Nuclear generation in MW.
        </ResponseField>

        <ResponseField name="thermal_mw" type="number">
          Thermal generation (gas, coal, and oil combined) in MW.
        </ResponseField>

        <ResponseField name="other_mw" type="number">
          All remaining generation sources not covered by the categories above, in MW.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cross_border_flows_mw" type="number">
      Net cross-border interconnection flow in MW. A **positive** value indicates net import into Spain; a **negative** value indicates net export.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "date": "2024-06-15",
  "data_as_of": "2024-06-15T10:47:00Z",
  "hours": [
    {
      "hour": 0,
      "total_load_mw": 26840.5,
      "generation": {
        "wind_mw": 8120.0,
        "solar_mw": 0.0,
        "hydro_mw": 3450.2,
        "nuclear_mw": 6700.0,
        "thermal_mw": 5910.4,
        "other_mw": 1380.0
      },
      "cross_border_flows_mw": 720.1
    },
    {
      "hour": 1,
      "total_load_mw": 25310.0,
      "generation": {
        "wind_mw": 8540.5,
        "solar_mw": 0.0,
        "hydro_mw": 3210.0,
        "nuclear_mw": 6700.0,
        "thermal_mw": 4730.0,
        "other_mw": 1340.0
      },
      "cross_border_flows_mw": 610.5
    }
  ]
}
```

## Error Responses

| HTTP Status        | Reason                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400 Bad Request`  | Missing required `date` parameter, invalid date format, or `hour` value outside the 0–23 range.                                                                                |
| `401 Unauthorized` | Missing, expired, or invalid Bearer token.                                                                                                                                     |
| `404 Not Found`    | No ENTSO-E fundamentals data is available for the requested date. This can occur for dates too far in the future or historical dates before Nexenergie's data coverage window. |

<Info>
  The `data_as_of` field reflects when ENTSO-E last published updates for this date. Fundamentals are updated multiple times daily as ENTSO-E refreshes its forecasts, so repeated calls for a future or current date may return progressively newer snapshots with revised values.
</Info>

<Tip>
  Compare `total_load_mw` against the sum of `generation.wind_mw` and `generation.solar_mw` across hours to identify periods of renewable surplus or deficit. These conditions are among the strongest structural drivers of OMIE price formation and are especially useful for validating or contextualising Nexenergie's price forecasts.
</Tip>