API Reference

Base URL: http://localhost:8000

All request bodies use JSON with camelCase keys. The interactive Swagger UI is available at /docs.

Endpoint Overview

Simulation

POST /simulate

Run a BESS simulation.

Query Parameters:

Parameter	Type	Default	Description
include_timeseries	bool	false	Include 15-min timeseries in response
include_heatmap	bool	false	Generate daily heatmap HTML

Request Body:

{
  "params": {
    "title": "Project X",
    "description": "10 MWh BESS with solar",
    "startProject": "2024-01-01",
    "projectLifeYears": 25,
    "bessCapacity": 10.0,
    "bessPower": 5.0,
    "bessMaximumSOC": 90,
    "bessMinimumSOC": 10,
    "bessRoundTripEfficiency": 90,
    "bessLifetimeCycles": 8000,
    "gridChargingCapacity": 10.0,
    "gridDischargingCapacity": 10.0,
    "gridTarif": "HT/LT",
    "gridStandingChargeTransport": 5000,
    "gridTransportedEnergy": 50,
    "economicsInflation": 0.02,
    "economicsDiscountRate": 0.05
  },
  "run": {
    "scenario_id": 1,
    "simulation_years": 5,
    "strategy": "rolling_lp",
    "enabled_markets": ["day_ahead", "afrr"],
    "foresight_days": 3,
    "execute_days": 1,
    "yearly_summary": true
  }
}

See Parameters for the complete parameter reference.

Response:

{
  "status": "success",
  "summary": {
    "financial": {
      "total_revenue_eur": 1250000,
      "net_revenue_eur": 175000,
      "npv_eur": 95000,
      "roi_percent": 3.5,
      "irr_percent": 8.2,
      "total_capex_eur": 1000000,
      "total_opex_eur": 75000,
      "day_ahead_revenue_eur": 80000,
      "afrr_capacity_revenue_eur": 45000,
      "solar_subsidy_revenue_eur": 50000
    },
    "operational": {
      "total_charge_mwh": 8500,
      "total_discharge_mwh": 8200,
      "total_cycles": 1850,
      "final_soh_percent": 82.5,
      "capacity_utilization_percent": 45.2,
      "average_rte_percent": 87.3,
      "replacement_events": 0
    },
    "trading": { "..." : "..." },
    "highlights": { "..." : "..." }
  },
  "timeseries": [],
  "yearly_summaries": [],
  "simulation_time_seconds": 4.23,
  "heatmap_html": "..."
}

POST /simulate/heatmap

Same as /simulate but returns a standalone HTML page with a daily performance heatmap visualization.

GET /example-config

Returns an example simulation configuration JSON that can be used as a starting point.

---

Scenarios

POST /scenarios

Create a new empty scenario.

{
  "name": "NL 2024",
  "country": "NL",
  "description": "Dutch market data 2024",
  "preload": true
}

Response: Scenario metadata with assigned id.

POST /scenarios/upload

Upload a scenario from a ZIP file containing CSV data.

Form Data:

Field	Type	Description
file	file	ZIP file with CSV data
name	string	Scenario name
country	string	Country code
description	string	Description
preload	bool	Auto-load to cache

The ZIP is scanned for files matching:

• *predictions* or *price* → price data
• *capacities* → installed capacities
• *annual_statistics* → annual statistics (XLSX)
• *modell* → unified price/aFRR/FCR import

GET /scenarios

List all scenarios (paginated).

Parameter	Type	Default	Description
limit	int	100	Results per page (1-1000)
offset	int	0	Skip N results

GET /scenarios/{scenario_id}

Get scenario metadata.

PUT /scenarios/{scenario_id}

Update scenario metadata (partial update). Accepts: name, country, description, preload.

DELETE /scenarios/{scenario_id}

Delete scenario and all associated data files.

POST /scenarios/{scenario_id}/preload

Toggle the preload flag.

{ "preload": true }

GET /scenarios/{scenario_id}/installed-capacities

Returns installed capacity data (if imported).

GET /scenarios/{scenario_id}/annual-statistics

Returns annual statistics data (if imported).

---

Scenario Data Import

POST /scenarios/{scenario_id}/import/price-data

Import price data from CSV.

Expected columns: datetime, DA_price_15min, ID3_price, Imb_Long_price, Imb_Short_price, Regulation_State, signal

POST /scenarios/{scenario_id}/import/solar-data

Import solar generation data from CSV.

Expected columns: timestamp, solar_output_mw

POST /scenarios/{scenario_id}/import/afrr-data

Import aFRR capacity price data. Auto-detects block duration (4h or 24h) and resamples to 15-min intervals.

Expected columns: timestamp, price_up, price_down

POST /scenarios/{scenario_id}/import/fcr-data

Import FCR capacity price data. Resamples to 15-min intervals.

Expected columns: timestamp, price

POST /scenarios/{scenario_id}/import/solar-wind-data

Import solar irradiance and wind speed constraint data.

Expected columns: time, wind_speed, irradiance_direct

---

Scenario Cache

GET /scenarios/cache/stats

Returns cache statistics: cached scenario count, preloaded count, memory usage (MB).

POST /scenarios/{scenario_id}/cache/load

Manually load scenario data into memory cache.

POST /scenarios/{scenario_id}/cache/unload

Remove scenario data from memory cache.

---

Profiles

POST /profiles

Generate a new solar or wind production profile using ERA5 weather data.

PV Example

{
  "name": "Solar NL 2024",
  "profile_type": "pv",
  "description": "Solar profile for Netherlands",
  "preload": true,
  "cutout_year": 2024,
  "config": {
    "latitude": 52.0,
    "longitude": 4.9,
    "capacity_mw": 10.0,
    "panel_type": "CSi",
    "slope": 35.0,
    "azimuth": 180.0,
    "tracking": "fixed",
    "system_loss": 0.1,
    "inverter_limit": 0.9
  }
}

Wind Example

{
  "name": "Wind NL 2024",
  "profile_type": "wind",
  "cutout_year": 2024,
  "config": {
    "latitude": 52.0,
    "longitude": 4.9,
    "capacity_mw": 5.0,
    "turbine_model": "Vestas_V90_3MW",
    "hub_height": 80,
    "interpolation": "logarithmic",
    "system_loss": 0.05
  }
}

Generation takes 30-60 seconds. Response includes profile metadata and statistics.

POST /profiles/upload

Import a profile from CSV.

Field	Type	Description
file	file	CSV with timestamp and output_mw columns
name	string	Profile name
profile_type	string	pv or wind
latitude	float	Location latitude
longitude	float	Location longitude
capacity_mw	float	Installed capacity

GET /profiles

List profiles (paginated). Optional profile_type filter (pv or wind).

GET /profiles/{profile_id}

Get profile metadata. Profile IDs are UUIDs.

PUT /profiles/{profile_id}

Update profile metadata. Accepts: name, description, preload.

DELETE /profiles/{profile_id}

Delete profile and all associated data.

GET /profiles/{profile_id}/data

Get timeseries data (paginated with limit and offset).

Response: Array of { timestamp, output_mw } records.

GET /profiles/{profile_id}/export

Download profile as CSV file.

POST /profiles/{profile_id}/preload

Toggle preload flag.

---

Profile Cache

GET /profiles/cache/stats

Cache statistics for profiles.

POST /profiles/{profile_id}/cache/load

Manually load profile to cache.

POST /profiles/{profile_id}/cache/unload

Remove profile from cache.

---

Profile Utilities

GET /profiles/cutouts

List available ERA5 cutout files (years available for profile generation).

GET /profiles/cutouts/{year}/info

Detailed information about a cutout file: coverage area, time range, resolution.

GET /profiles/turbines

List available wind turbine models for profile generation.

---

Utility

GET /health

Health check. Returns API status and cache statistics.

GET /

API information and version.

GET /docs

Interactive Swagger UI documentation.

GET /redoc

ReDoc API documentation.