API Documentation

curl -H "Authorization: Bearer st_live_abc123def456..." \
  https://suntrace3d.com/api/v1/models

curl -X POST https://suntrace3d.com/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 44.8699,
    "longitude": 13.8420,
    "radiusKm": 0.3
  }'

{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "pending"
}

{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "ready",
  "modelUrl": "https://s3.eu-central-1.amazonaws.com/suntrace-models/hd_44.8699_13.8420_0.3/scene.glb"
}

curl https://suntrace3d.com/api/v1/models/hd_44.8699_13.8420_0.3 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "processing",
  "progress": 65,
  "step": "Generating textures..."
}

{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "ready",
  "modelUrl": "https://s3.eu-central-1.amazonaws.com/suntrace-models/hd_44.8699_13.8420_0.3/scene.glb",
  "progress": 100,
  "step": null
}

curl -X POST https://suntrace3d.com/api/solar/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 44.8699,
    "longitude": 13.8420,
    "tiltDeg": 35,
    "azimuthDeg": 180,
    "panelAreaM2": 20,
    "panelEfficiency": 0.20,
    "shadingLossFraction": 0.05
  }'

{
  "annualYieldKwh": 4982,
  "peakPowerKw": 4.0,
  "specificYield": 1246,
  "monthlyKwh": [248, 305, 412, 465, 522, 548, 562, 530, 445, 368, 280, 232],
  "source": "pvgis"
}

<iframe
  src="https://suntrace3d.com/embed?lat=44.8699&lng=13.8420&key=YOUR_API_KEY"
  width="100%"
  height="500"
  frameborder="0"
  allow="fullscreen"
  style="border-radius: 12px; border: 1px solid #e5e7eb;">
</iframe>

<div style="position: relative; width: 100%; padding-bottom: 56.25%; overflow: hidden; border-radius: 12px;">
  <iframe
    src="https://suntrace3d.com/embed?lat=44.8699&lng=13.8420&key=YOUR_API_KEY"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    allow="fullscreen">
  </iframe>
</div>

{
  "error": "Rate limit exceeded. Maximum 10 generations per hour."
}

{
  "error": "latitude and longitude are required"
}

{
  "error": "Invalid or revoked API key"
}

#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://suntrace3d.com"

# 1. Request model generation
echo "Requesting model generation..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 44.8699, "longitude": 13.8420, "radiusKm": 0.3}')

MODEL_ID=$(echo $RESPONSE | jq -r '.id')
STATUS=$(echo $RESPONSE | jq -r '.status')
echo "Model ID: $MODEL_ID (status: $STATUS)"

# 2. Poll until ready
while [ "$STATUS" != "ready" ] && [ "$STATUS" != "failed" ]; do
  sleep 5
  RESPONSE=$(curl -s "$BASE_URL/api/v1/models/$MODEL_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $RESPONSE | jq -r '.status')
  PROGRESS=$(echo $RESPONSE | jq -r '.progress // 0')
  echo "Status: $STATUS ($PROGRESS%)"
done

# 3. Get the model URL
if [ "$STATUS" = "ready" ]; then
  MODEL_URL=$(echo $RESPONSE | jq -r '.modelUrl')
  echo "Model ready: $MODEL_URL"
else
  echo "Generation failed"
fi

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://suntrace3d.com';

async function generateModel(lat, lng) {
  // 1. Request generation
  const res = await fetch(`${BASE_URL}/api/v1/models`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ latitude: lat, longitude: lng }),
  });

  const { id, status, modelUrl } = await res.json();

  // If already cached, return immediately
  if (status === 'ready') return { id, modelUrl };

  // 2. Poll until ready
  return pollStatus(id);
}

async function pollStatus(modelId) {
  while (true) {
    await new Promise(r => setTimeout(r, 5000)); // Wait 5s

    const res = await fetch(`${BASE_URL}/api/v1/models/${modelId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    });

    const data = await res.json();
    console.log(`Status: ${data.status} (${data.progress || 0}%)`);

    if (data.status === 'ready') return data;
    if (data.status === 'failed') throw new Error('Generation failed');
  }
}

// Usage
generateModel(44.8699, 13.8420)
  .then(data => console.log('Model URL:', data.modelUrl))
  .catch(err => console.error(err));

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://suntrace3d.com"

def generate_model(lat: float, lng: float) -> dict:
    """Generate an HD 3D model and wait for completion."""
    # Request generation
    res = requests.post(
        f"{BASE_URL}/api/v1/models",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"latitude": lat, "longitude": lng, "radiusKm": 0.3},
    )
    data = res.json()

    if data["status"] == "ready":
        return data

    # Poll until ready
    model_id = data["id"]
    while True:
        time.sleep(5)
        res = requests.get(
            f"{BASE_URL}/api/v1/models/{model_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        data = res.json()
        print(f"Status: {data['status']} ({data.get('progress', 0)}%)")

        if data["status"] == "ready":
            return data
        if data["status"] == "failed":
            raise Exception("Generation failed")

def calculate_solar(lat: float, lng: float, tilt: float = 35, azimuth: float = 180) -> dict:
    """Calculate solar energy yield for a panel configuration."""
    res = requests.post(
        f"{BASE_URL}/api/solar/calculate",
        json={
            "latitude": lat,
            "longitude": lng,
            "tiltDeg": tilt,
            "azimuthDeg": azimuth,
            "panelAreaM2": 20,
            "panelEfficiency": 0.20,
        },
    )
    return res.json()

# Usage
model = generate_model(44.8699, 13.8420)
print(f"Model URL: {model['modelUrl']}")

solar = calculate_solar(44.8699, 13.8420)
print(f"Annual yield: {solar['annualYieldKwh']} kWh")
print(f"Monthly: {solar['monthlyKwh']}")

{
  "agentName": "ChatGPT",
  "latitude": 44.8699,
  "longitude": 13.8420,
  "wizardGoal": "cover_bill",
  "wizardKwh": 350,
  "roofLat": 44.8701,
  "roofLng": 13.8418
}

{
  "sessionId": "clxyz...",
  "viewerUrl": "https://suntrace3d.com/viewer?session=clxyz...&lat=44.869900&lng=13.842000&wizard=cover_bill&wizardKwh=350&roofLat=44.8701000&roofLng=13.8418000",
  "status": "created",
  "modelStatus": "not_generated",
  "agentName": "ChatGPT"
}

import requests

def create_solar_link(lat, lng, roof_lat=None, roof_lng=None, monthly_kwh=None):
    """Create an agent session and return the viewer URL."""
    payload = {
        "agentName": "MySolarBot",
        "latitude": lat,
        "longitude": lng,
        "wizardGoal": "cover_bill" if monthly_kwh else "maximize_energy",
    }
    if monthly_kwh:
        payload["wizardKwh"] = monthly_kwh
    if roof_lat is not None and roof_lng is not None:
        payload["roofLat"] = roof_lat
        payload["roofLng"] = roof_lng

    res = requests.post("https://suntrace3d.com/api/mcp-sessions", json=payload)
    res.raise_for_status()
    return res.json()["viewerUrl"]

# Usage — send this link to the user
url = create_solar_link(
    lat=44.8699, lng=13.8420,
    roof_lat=44.8701, roof_lng=13.8418,
    monthly_kwh=350,
)
print(f"Send this to your user: {url}")
# User clicks -> model generates (~1-2 min) -> wizard auto-opens -> panels placed