Asoba Ona Documentation
Home Insights Contact Us

API Reference

Complete documentation for all Ona API endpoints and services.

Overview

The Ona API provides comprehensive energy management, forecasting, and analysis capabilities through a suite of specialized endpoints. Each API is designed for specific use cases in energy asset management, forecasting, and optimization.

Current Development State

Last Updated: 2025-01-10 (Status: PRODUCTION VERIFIED - Version 1.6.0)

Platform Architecture

The Ona Platform follows a layered architecture:

  1. Data Ingestion Layer: Historical and real-time data collection
  2. Processing Layer: Data enrichment, interpolation, and ML training
  3. API Layer: RESTful endpoints for forecasting and analysis
  4. Application Layer: OODA workflow for operational decisions

Service Capabilities

Authentication

All API requests require authentication using API keys:

# Set your API key in headers
curl -H "x-api-key: YOUR_API_KEY" https://api.asoba.co/ingestHistorical

Base URLs

The Ona API uses a unified API Gateway endpoint:

Production Endpoint

Regional Deployment

Service Endpoints

Core APIs

🔌 Data Ingestion APIs

Ingest Historical Load Data

Endpoint: /ingestHistorical

Base URL: https://api.asoba.co

Upload and process historical energy usage data for model training and analysis.

Method: POST

Parameters:

Example:

curl -X POST "https://yn058ezh38.execute-api.af-south-1.amazonaws.com/prod/ingestHistorical" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -F "customer_id=your-customer-id" \
  -F "filename=historical_data.csv" \
  -F "manufacturer=SolarEdge" \
  -F "location=CapeTown" \
  -F "region=af-south-1" \
  --data-binary @your-data.csv

Ingest Nowcast Load Data

Endpoint: /ingestNowcast

Base URL: https://api.asoba.co

Upload real-time energy data for immediate processing and analysis.

Method: POST

Parameters:

Example:

curl -X POST "https://xkg3s0npv0.execute-api.af-south-1.amazonaws.com/prod/ingestNowcast" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "your-customer-id",
    "data": {"power": 150.5, "voltage": 240.0},
    "timestamp": "2024-01-15T10:30:00Z",
    "region": "af-south-1"
  }'

🔄 Data Processing APIs

Interpolate Data

Endpoint: /dataInterpolation

Base URL: https://ul4rjb4twc.execute-api.af-south-1.amazonaws.com/prod

Process and fill gaps in time-series data using advanced interpolation methods.

Method: POST

Parameters:

Example:

curl -X POST "https://ul4rjb4twc.execute-api.af-south-1.amazonaws.com/prod/dataInterpolation" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "your-customer-id",
    "data": [
      {"timestamp": "2024-01-15T10:00:00Z", "value": 100.0},
      {"timestamp": "2024-01-15T10:15:00Z", "value": null},
      {"timestamp": "2024-01-15T10:30:00Z", "value": 120.0}
    ],
    "interpolation_method": "linear",
    "region": "af-south-1"
  }'

🤖 Machine Learning APIs

Train Forecaster

Endpoint: /

Base URL: https://api.asoba.co

Train machine learning models on historical data for energy forecasting.

Method: POST

Parameters:

Example:

curl -X POST "https://x0o7xd1uq7.execute-api.af-south-1.amazonaws.com/prod/" \
  -H "x-api-key: YOUR_API_KEY" \
  -G \
  -d "customer_id=your-customer-id" \
  -d "location=CapeTown" \
  -d "manufacturer=SolarEdge" \
  -d "serial_number=SE123456" \
  -d "region=af-south-1" \
  -d "testing=true"

Generate Forecast

Endpoint: /forecast

Status: ⚠️ NOT DEPLOYED - Core module exists but no API Gateway deployed

Note: This endpoint is part of Epic #139 (Customer-Facing Features) and requires completion of security and production infrastructure epics first.

Method: POST

Parameters:

Example: (Not available until deployed)

# This endpoint will be available after Epic #139 completion
# Expected base URL: https://[api-gateway-id].execute-api.af-south-1.amazonaws.com/prod

Return Forecasting Results

Endpoint: /returnForecastingResults

Retrieve forecast outputs and analysis results.

Method: GET

Parameters:

Example:

curl -X GET "https://api.asoba.co/returnForecastingResults" \
  -H "x-api-key: YOUR_API_KEY" \
  -G \
  -d "customer_id=your-customer-id" \
  -d "forecast_id=forecast-123" \
  -d "region=af-south-1"

⚡ Energy Management APIs

Electricity Dispatch

Endpoint: /electricityDispatch

Optimize energy dispatch and scheduling for maximum efficiency.

Method: POST

Parameters:

Example:

curl -X POST "https://yn058ezh38.execute-api.af-south-1.amazonaws.com/prod/electricityDispatch" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "your-customer-id",
    "dispatch_period": "daily",
    "constraints": {
      "max_power": 1000,
      "min_power": 100
    },
    "region": "af-south-1"
  }'

Market Price Forecast

Endpoint: /marketPriceForecast

Predict electricity market prices for trading and optimization.

Method: POST

Parameters:

Example:

curl -X POST "https://api.asoba.co/marketPriceForecast" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "market": "ESKOM",
    "forecast_horizon": 48,
    "model_type": "lstm",
    "region": "af-south-1"
  }'

🌤️ Weather Integration APIs

Weather Data

Endpoint: /weather

Integrate weather data for enhanced forecasting accuracy.

Method: GET

Parameters:

Example:

curl -X GET "https://yn058ezh38.execute-api.af-south-1.amazonaws.com/prod/weather" \
  -H "x-api-key: YOUR_API_KEY" \
  -G \
  -d "location=CapeTown" \
  -d "data_type=forecast" \
  -d "region=af-south-1"

📋 Management APIs

Manage Users

Endpoint: /manageUsers

User management and access control operations.

Method: POST

Parameters:

Example:

curl -X POST "https://yn058ezh38.execute-api.af-south-1.amazonaws.com/prod/manageUsers" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "user_data": {
      "email": "user@example.com",
      "role": "analyst",
      "permissions": ["read", "forecast"]
    },
    "region": "af-south-1"
  }'

Policy Compliance

Endpoint: /policyCompliance

Regulatory compliance checking and policy analysis.

Method: POST

Parameters:

Example:

curl -X POST "https://api.asoba.co/policyCompliance" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "your-customer-id",
    "policy_type": "renewable_energy",
    "data": {
      "energy_source": "solar",
      "capacity": 1000,
      "location": "CapeTown"
    },
    "region": "af-south-1"
  }'

Response Formats

Success Response

{
  "status": "success",
  "data": {
    // Response data specific to the endpoint
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req-123456"
}

Error Response

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter provided",
    "details": {
      "field": "customer_id",
      "issue": "Required field missing"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req-123456"
}

Error Codes

Code Description
AUTHENTICATION_ERROR Invalid or missing API key
VALIDATION_ERROR Invalid request parameters
RATE_LIMIT_EXCEEDED Too many requests
RESOURCE_NOT_FOUND Requested resource not found
INTERNAL_ERROR Server error

Rate Limits

SDK Integration

For easier integration, use our official SDKs:

Python SDK

from ona_sdk import OnaClient

client = OnaClient(api_key="your-api-key")

# Generate forecast
result = client.generate_forecast(
    customer_id="your-id",
    forecast_horizon=24,
    region="af-south-1"
)

JavaScript SDK

const OnaClient = require('ona-sdk');

const client = new OnaClient('your-api-key');

// Generate forecast
const result = await client.generateForecast({
  customerId: 'your-id',
  forecastHorizon: 24,
  region: 'af-south-1'
});

Testing

Use our test endpoints for development and testing:

# Test API connection
curl -H "x-api-key: YOUR_API_KEY" https://api.asoba.co/health

# Test with sample data
curl -X POST "https://api.asoba.co/test/forecast" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Support

Get Help & Stay Updated

Contact Support

For technical assistance, feature requests, or any other questions, please reach out to our dedicated support team.

Email Support Join Our Discord

Subscribe to Updates

* indicates required