API Documentation

Authorization: Bearer azk_your_api_key_here

x-api-key: azk_your_api_key_here

https://azuce.com/api/v1

POST https://azuce.com/api/v1/forecast
Content-Type: application/json
Authorization: Bearer azk_your_api_key_here

{
  "latitude": 51.5074,
  "longitude": -0.1278,
  "systemSizeKw": 4.0,
  "panelAzimuth": 180,
  "panelTilt": 35
}

GET https://azuce.com/api/v1/forecast

{
  "forecast": {
    "monthlyKwh": [
      120.5, 145.2, 210.8, 280.3, 340.1,
      365.7, 370.2, 345.6, 270.4, 195.3,
      135.6, 105.8
    ],
    "annualKwh": 2885.5,
    "conservativeAnnual": 2597.0,
    "optimisticAnnual": 3174.1,
    "weatherNote": "Current conditions: partly cloudy, 18°C...",
    "modelVersion": "1.0.0",
    "location": {
      "latitude": 51.5074,
      "longitude": -0.1278,
      "address": "London, UK"
    },
    "system": {
      "systemSizeKw": 4.0,
      "panelAzimuth": 180,
      "panelTilt": 35,
      "shadingLoss": 0,
      "systemLosses": 14
    }
  },
  "financialAnalysis": {
    "annualSavings": 242.38,
    "annualExportIncome": 100.99,
    "annualMaintenanceCost": 150,
    "annualNetBenefit": 193.37,
    "simplePaybackYears": 10.34,
    "totalBenefit25Years": 4381.52,
    "roi25YearPercent": 119.08,
    "selfConsumption": {
      "selfUsedKwh": 865.65,
      "exportedKwh": 2019.85,
      "selfConsumptionPercent": 30
    },
    "inputs": {
      "installedCost": 2000,
      "electricityRate": 0.28,
      "exportRate": 0.05,
      "selfConsumptionPct": 30,
      "annualMaintenanceCost": 150,
      "annualDegradationPct": 0.5
    },
    "yearlyBreakdown": [
      { "year": 1, "productionKwh": 2885.5, "netBenefit": 193.37, "cumulativeBenefit": 193.37 },
      { "year": 2, "productionKwh": 2871.07, "netBenefit": 191.65, "cumulativeBenefit": 385.02 }
    ]
  },
  "carbonImpact": {
    "annualCo2AvoidedKg": 672.32,
    "equivalentMilesDriven": 1664,
    "equivalentTreesPlanted": 32.02,
    "gridKgCo2PerKwh": 0.233,
    "lifetimeCo2AvoidedKg": 16808.0
  },
  "usage": {
    "callsThisMonth": 42,
    "freeCallsRemaining": 458,
    "billableCallsThisMonth": 0,
    "estimatedCostUsd": 0
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Include your key via Authorization: Bearer <key> or x-api-key header."
}

{
  "error": "Validation Error",
  "message": "Invalid input parameters",
  "details": [
    { "field": "latitude", "message": "Number must be greater than or equal to -90" },
    { "field": "systemSizeKw", "message": "Required" }
  ]
}

{
  "error": "Rate Limited",
  "message": "External data source is temporarily rate-limited. Please retry in a few seconds."
}

// Exponential backoff example
const delays = [1000, 2000, 4000, 8000]; // milliseconds
for (const delay of delays) {
  const response = await fetch(url, options);
  if (response.status !== 429) break;
  await new Promise(r => setTimeout(r, delay));
}

curl -X POST https://azuce.com/api/v1/forecast \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer azk_your_api_key_here" \
  -d '{
    "latitude": 51.5074,
    "longitude": -0.1278,
    "systemSizeKw": 4.0,
    "panelAzimuth": 180,
    "panelTilt": 35
  }'

import requests

API_KEY = "azk_your_api_key_here"
URL = "https://azuce.com/api/v1/forecast"

response = requests.post(
    URL,
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={
        "latitude": 51.5074,
        "longitude": -0.1278,
        "systemSizeKw": 4.0,
        "panelAzimuth": 180,
        "panelTilt": 35,
    },
)

data = response.json()
forecast = data["forecast"]

print(f"Annual Production: {forecast['annualKwh']:.0f} kWh")
print(f"Range: {forecast['conservativeAnnual']:.0f} - {forecast['optimisticAnnual']:.0f} kWh")
print(f"Monthly: {[round(m) for m in forecast['monthlyKwh']]}")
print(f"Weather: {forecast['weatherNote']}")

const API_KEY = "azk_your_api_key_here";

const response = await fetch("https://azuce.com/api/v1/forecast", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    latitude: 51.5074,
    longitude: -0.1278,
    systemSizeKw: 4.0,
    panelAzimuth: 180,
    panelTilt: 35,
  }),
});

const data = await response.json();

console.log("Annual:", data.forecast.annualKwh, "kWh");
console.log("Conservative:", data.forecast.conservativeAnnual, "kWh");
console.log("Optimistic:", data.forecast.optimisticAnnual, "kWh");
console.log("Monthly:", data.forecast.monthlyKwh);
console.log("Usage:", data.usage.callsThisMonth, "/", 500, "free calls used");

<?php
$apiKey = "azk_your_api_key_here";

$ch = curl_init("https://azuce.com/api/v1/forecast");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer $apiKey",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "latitude" => 51.5074,
        "longitude" => -0.1278,
        "systemSizeKw" => 4.0,
        "panelAzimuth" => 180,
        "panelTilt" => 35,
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$forecast = $data["forecast"];

echo "Annual: " . round($forecast["annualKwh"]) . " kWh\n";
echo "Range: " . round($forecast["conservativeAnnual"]) . " - " . round($forecast["optimisticAnnual"]) . " kWh\n";

curl -X POST https://azuce.com/api/v1/forecast \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer azk_your_api_key_here" \
  -d '{
    "latitude": 51.5074,
    "longitude": -0.1278,
    "systemSizeKw": 4.0,
    "panelAzimuth": 180,
    "panelTilt": 35,
    "enableFinancials": true,
    "installedCost": 8000,
    "electricityRate": 0.28,
    "exportRate": 0.05,
    "selfConsumptionPct": 40,
    "annualDegradationPct": 0.5,
    "currencyCode": "GBP",
    "currencySymbol": "£",
    "countryCode": "GB",
    "enableCarbon": true,
    "gridKgCo2PerKwh": 0.233
  }'

import requests
import time
import json

API_KEY = "azk_your_api_key_here"
URL = "https://azuce.com/api/v1/forecast"

sites = [
    {"name": "London Office",    "lat": 51.5074, "lng": -0.1278},
    {"name": "Berlin Warehouse", "lat": 52.5200, "lng": 13.4050},
    {"name": "Madrid Factory",   "lat": 40.4168, "lng": -3.7038},
    {"name": "Sydney HQ",       "lat": -33.8688, "lng": 151.2093},
]

results = []
for site in sites:
    response = requests.post(
        URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "latitude": site["lat"],
            "longitude": site["lng"],
            "systemSizeKw": 10.0,
            "panelAzimuth": 180,
            "panelTilt": 30,
        },
    )

    if response.status_code == 429:
        time.sleep(5)  # Retry after rate limit
        response = requests.post(URL, headers={"Authorization": f"Bearer {API_KEY}"}, json={...})

    data = response.json()
    results.append({
        "site": site["name"],
        "annual_kwh": data["forecast"]["annualKwh"],
        "range": f"{data['forecast']['conservativeAnnual']:.0f}-{data['forecast']['optimisticAnnual']:.0f}",
    })
    time.sleep(0.3)  # Space out requests

for r in results:
    print(f"{r['site']}: {r['annual_kwh']:.0f} kWh ({r['range']} kWh)")