API Documentation - Energy Simulations Platform

Overview

The Energy Simulations API provides RESTful endpoints for energy price prediction, solar production estimation, and battery storage optimization. All endpoints accept and return JSON data.

Interactive Documentation

For interactive API testing, visit the Swagger UI which allows you to try endpoints directly in your browser.

Base URL

                        Base URL
                    
                        http://localhost:8000

All API endpoints are relative to this base URL. In production, replace with your deployment URL.

Authentication

Currently, the API does not require authentication for public datasets and models. Private resources require session-based authentication via the web interface.

GET /health

Check if the API is running and get system status information.

200 Success

Response Body

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "2.0.0",
  "mode": "full"
}
                            

cURL

curl -X GET http://localhost:8000/health

GET /api/datasets

Retrieve a list of all available datasets (public and private).

Parameters

Name	Type	Description
include_publicoptional	boolean	Include public datasets in the response. Default: true

200 Success

Response Body

{
  "datasets": [
    {
      "name": "energy_prices_2024.csv",
      "type": "public",
      "rows": 8760,
      "columns": 5,
      "uploaded_at": "2024-01-01T00:00:00Z"
    }
  ]
}
                        

POST /api/upload-dataset

Upload a new dataset to the platform. Accepts CSV files up to 50MB.

Request Body (multipart/form-data)

Field	Type	Description
filerequired	file	CSV file to upload
is_publicoptional	boolean	Make dataset publicly accessible. Default: false

cURL

curl -X POST http://localhost:8000/api/upload-dataset \
  -F "file=@energy_data.csv" \
  -F "is_public=false"
                        

Python (requests)

import requests

url = "http://localhost:8000/api/upload-dataset"
files = {"file": open("energy_data.csv", "rb")}
data = {"is_public": "false"}

response = requests.post(url, files=files, data=data)
print(response.json())
                        

JavaScript (fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('is_public', 'false');

const response = await fetch('http://localhost:8000/api/upload-dataset', {
  method: 'POST',
  body: formData
});
const result = await response.json();
                        

POST /train/{model_type}

Train a machine learning model on a dataset. Supported types: price, production.

Path Parameters

Name	Type	Description
model_typerequired	string	Type of model: "price" or "production"

Request Body (JSON)

Field	Type	Description
dataset_pathrequired	string	Path to the dataset file
target_columnrequired	string	Column name to predict
model_nameoptional	string	Custom name for the saved model
algorithmoptional	string	"random_forest" or "neural_network". Default: random_forest

Example Request

{
  "dataset_path": "public/energy_prices.csv",
  "target_column": "price",
  "model_name": "my_price_model",
  "algorithm": "random_forest"
}
                    

200 Success

Response Body

{
  "status": "success",
  "model_path": "own/my_price_model.pkl",
  "metrics": {
    "r2": 0.87,
    "rmse": 4.23,
    "mae": 3.15
  },
  "training_time": 12.5
}
                        

POST /predict/{model_type}

Make predictions using a trained model. Supports both single and batch predictions.

Request Body (JSON)

Field	Type	Description
model_pathrequired	string	Path to the trained model file
featuresrequired	object \| array	Feature values for prediction (single object or array for batch)

Single Prediction Request

{
  "model_path": "own/my_price_model.pkl",
  "features": {
    "demand": 52100,
    "renewable_share": 0.42,
    "temperature": 18.5
  }
}
                        

Batch Prediction Request

{
  "model_path": "own/my_price_model.pkl",
  "features": [
    {"demand": 52100, "renewable_share": 0.42},
    {"demand": 48900, "renewable_share": 0.45},
    {"demand": 55300, "renewable_share": 0.38}
  ]
}
                        

POST /simulate

Run a battery storage simulation with specified parameters.

Request Body (JSON)

Field	Type	Description
dataset_pathrequired	string	Path to price dataset
battery_capacityrequired	number	Battery capacity in kWh
charge_rateoptional	number	Charging rate in kW. Default: capacity / 4
efficiencyoptional	number	Round-trip efficiency (0-1). Default: 0.9

Example Request

{
  "dataset_path": "public/energy_prices.csv",
  "battery_capacity": 10.0,
  "charge_rate": 2.5,
  "efficiency": 0.9
}
                    

GET /api/solar/potential

Get solar production potential for a specific location.

Query Parameters

Name	Type	Description
latrequired	number	Latitude (-90 to 90)
lonrequired	number	Longitude (-180 to 180)
capacity_kwpoptional	number	System capacity in kWp. Default: 1.0

Example Request

GET /api/solar/potential?lat=52.52&lon=13.405&capacity_kwp=5.0

200 Success

Response Body

{
  "location": {
    "lat": 52.52,
    "lon": 13.405,
    "city": "Berlin"
  },
  "annual_production_kwh": 4875,
  "monthly_production": [...],
  "peak_sun_hours": 3.5
}
                        