Integration Examples

Starting the Server

# Conda
conda activate buem_env
python -m buem.apis.api_server

# Docker
docker compose up

Health Check

curl http://localhost:5000/api/health

Process a GeoJSON File

curl -X POST http://localhost:5000/api/process \
   -H "Content-Type: application/json" \
   -d @src/buem/integration/sample_request_template.geojson

To include hourly time-series in the response:

curl -X POST "http://localhost:5000/api/run?include_timeseries=true" \
   -H "Content-Type: application/json" \
   --data-binary @payload.json

Python Helper

BuEM ships a convenience script for submitting requests:

python -m buem.integration.send_geojson \
    src/buem/integration/sample_request_template.geojson \
    --include-timeseries

Minimal Python Client

import requests

payload = {
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "id": "B001",
        "geometry": {"type": "Point", "coordinates": [5.0, 52.0]},
        "properties": {
            "buem": {
                "building_attributes": {
                    "latitude": 52.0,
                    "longitude": 5.0,
                    "A_ref": 100.0,
                    "components": {
                        "Walls": {"U": 1.5, "elements": [
                            {"id": "W1", "area": 80, "azimuth": 180, "tilt": 90}
                        ]},
                        "Ventilation": {"elements": [
                            {"id": "V1", "air_changes": 0.5}
                        ]}
                    }
                }
            }
        }
    }]
}

resp = requests.post("http://localhost:5000/api/process", json=payload, timeout=60)
resp.raise_for_status()
result = resp.json()

thermal = result["features"][0]["properties"]["buem"]["thermal_load_profile"]
print(f"Heating: {thermal['heating_total_kWh']:.0f} kWh/yr")
print(f"Cooling: {thermal['cooling_total_kWh']:.0f} kWh/yr")

Downloading Time-Series Files

When include_timeseries=true, the response contains a timeseries_file path. Retrieve it with:

curl -O http://localhost:5000/api/files/buem_ts_<hash>.json.gz

Result Forwarding

Add forward_url to the request payload to have BuEM POST results to an external endpoint automatically:

{
    "forward_url": "https://example.com/receiver",
    "include_timeseries": false
}

Environment Variables

Variable	Description
BUEM_WEATHER_DIR	Path to weather CSV directory
BUEM_CBC_EXE	Path to CBC solver binary (MILP only)
BUEM_RESULTS_DIR	Directory for saved result files
BUEM_LOG_FILE	Log file path (default: logs/buem_api.log)