API Reference: Freemium Forecasting API

This document provides a detailed reference for the Freemium Forecasting API, which allows you to generate a 24-hour forecast from a CSV file of historical data. This is a simplified endpoint designed for quick testing and evaluation.

Note: For production use with trained models, see the Generate Forecast endpoint which uses the ForecastResponse.json schema.

This API is designed for Developers.

Endpoints

The freemium API is served from its own branded domain, forecasting.api.asoba.org, and uses a two-step email-verification flow:

POST https://forecasting.api.asoba.org/api/v1/freemium-forecast/verify   # Step 1: request a code
POST https://forecasting.api.asoba.org/api/v1/freemium-forecast          # Step 2: submit the forecast

forecasting.api.asoba.org is the freemium tier only. The metered/production forecasting endpoint (/forecast) is served from api.asoba.org — see Generate Forecast.

Step 1 — Request a verification code

POST /api/v1/freemium-forecast/verify with a JSON body containing your email. A one-time code is emailed to that address.

{ "email": "you@example.com" }

Step 2 — Submit the forecast request

POST /api/v1/freemium-forecast as a multipart/form-data request with the parameters below.

Request Parameters (Step 2)

The following parameters must be included in your multipart/form-data request:

SDK (Recommended)

Install the SDK from github.com/AsobaCloud/sdk. No API key needed.

Python:

from ona_platform import OnaClient

client = OnaClient()

# Step 1 — request a one-time code (emailed to you)
client.freemium_forecast.request_verification_code(email="you@example.com")

# Step 2 — submit the CSV with the code from your email
result = client.freemium_forecast.get_forecast(
    csv_path="data.csv",
    email="you@example.com",
    verification_code="123456",
    site_name="My Solar Site",
    location="Durban",
    capacity_kw=500.0,
    tou_accepted=True,       # required: accept the Terms of Use
    marketing_opt_in=False,  # optional
)

forecast = result["forecast"]
print(f"Total 24h: {forecast['summary']['total_kwh_24h']} kWh")

for point in forecast["forecasts"]:
    print(f"{point['timestamp']}: {point['kWh_forecast']} kWh")

JavaScript:

const { OnaSDK } = require('./src/index');

const sdk = new OnaSDK();

// Step 1 — request a one-time code (emailed to you)
await sdk.freemiumForecast.requestVerificationCode({ email: 'you@example.com' });

// Step 2 — submit the CSV with the code from your email
const result = await sdk.freemiumForecast.getForecast({
  csvPath: 'data.csv',
  email: 'you@example.com',
  verificationCode: '123456',
  siteName: 'My Solar Site',
  location: 'Durban',
  capacityKw: 500.0,
  touAccepted: true,      // required: accept the Terms of Use
  marketingOptIn: false,  // optional
});

const { forecast } = result;
console.log(`Total 24h: ${forecast.summary.total_kwh_24h} kWh`);

forecast.forecasts.forEach(p =>
  console.log(`${p.timestamp}: ${p.kWh_forecast} kWh`)
);

Full runnable examples:

• Python example
• JavaScript example

cURL Example

# Step 1 — request a verification code (emailed to you)
curl -X POST https://forecasting.api.asoba.org/api/v1/freemium-forecast/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Step 2 — submit the CSV with the code from your email
curl -X POST \
  -F "file=@/path/to/your/sample.csv" \
  -F "email=user@example.com" \
  -F "verification_code=123456" \
  -F "site_name=My First Solar Site" \
  -F "location=Durban" \
  -F "capacity_kw=500" \
  -F "tou_accepted=true" \
  https://forecasting.api.asoba.org/api/v1/freemium-forecast

Response Format

A successful request will return a 200 OK status code and a JSON object with the forecast data.

Successful Response Body

{
  "status": "success",
  "forecast": {
    "site_name": "My First Solar Site",
    "location": "Durban",
    "manufacturer": "Huawei",
    "forecast_hours": 24,
    "generated_at": "2025-12-30T10:00:00Z",
    "model_type": "generic",
    "forecasts": [
      {
        "timestamp": "2025-12-30T11:00:00Z",
        "hour_ahead": 1,
        "kWh_forecast": 15.5,
        "confidence": 0.85
      },
      {
        "timestamp": "2025-12-30T12:00:00Z",
        "hour_ahead": 2,
        "kWh_forecast": 65.2,
        "confidence": 0.85
      }
    ],
    "summary": {
      "total_kwh_24h": 28500.5,
      "peak_hour": "2025-12-30T14:00:00Z",
      "peak_kwh": 1850.2,
      "average_hourly_kwh": 1187.5
    }
  }
}

Error Responses

If the request is invalid or an error occurs during processing, the API will return an appropriate HTTP status code and a JSON error object.

Example Error Response (400 Bad Request)

{
  "status": "error",
  "error": "CSV file is required"
}