# Solar Thermal API
> Solar-thermal (solar hot water) maths as an API, computed locally and deterministically — the collector, sizing and storage numbers a solar installer or homeowner designs a hot-water system with. The output endpoint gives the useful daily heat a collector makes: area × the daily solar energy on it × the collector efficiency (flat-plate ~40–60 %, evacuated tubes higher), so a 40 ft² collector under 1,800 BTU/ft²/day at 50 % delivers about 36,000 BTU (10.5 kWh) — a family's hot water on a good day. The area endpoint sizes the collector for a demand: area = (daily gallons × 8.34 × the temperature rise) ÷ (irradiance × efficiency), so 60 gallons raised 70 °F needs about 39 ft² — sized for an average day with a backup heater, since a 60–80 % solar fraction is the economic sweet spot. The tank endpoint sizes solar storage at about 1.5 gallons per square foot of collector, big enough to bank a sunny afternoon without stalling the collector. Everything is computed locally and deterministically, so it is instant and private. Ideal for solar-installer and renewable-energy apps, hot-water-system design tools, home-energy calculators, and sustainability sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For the local solar resource use a solar-irradiance API; for pool heating use a pool API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/solarthermal-api/..."
```

## Pricing
- **Free** (Free) — 510 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 13,300 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 83,500 calls/Mo, 15 req/s
- **Mega** ($50/Mo) — 268,000 calls/Mo, 36 req/s

## Endpoints

### Solar Thermal

#### `GET /v1/area` — Collector area for a demand

**Parameters:**
- `daily_hot_water_gallons` (query, required, string) — Daily hot water in gallons Example: `60`
- `temp_rise_f` (query, required, string) — Temperature rise in °F Example: `70`
- `daily_irradiance_btu_sqft` (query, required, string) — Daily irradiance (BTU/ft²/day) Example: `1800`
- `efficiency_pct` (query, optional, string) — Collector efficiency % (default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarthermal-api/v1/area?daily_hot_water_gallons=60&temp_rise_f=70&daily_irradiance_btu_sqft=1800&efficiency_pct=50"
```

**Response:**
```json
{
    "data": {
        "note": "Collector area = the daily heat needed (gallons × 8.34 × temperature rise) ÷ (irradiance × efficiency). Size for an average day, not the sunniest — a solar fraction of 60–80 % with a backup heater is usually the economic sweet spot, since chasing 100 % needs a huge array for the worst weeks.",
        "inputs": {
            "temp_rise_f": 70,
            "efficiency_pct": 50,
            "daily_hot_water_gallons": 60,
            "daily_irradiance_btu_sqft": 1800
        },
        "collector_area_sqft": 38.9,
        "daily_heat_needed_btu": 35028
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:57.245Z",
        "request_id": "e9a4c167-2310-4970-9987-67a9a0e31c9b"
    },
    "status": "ok",
    "message": "Collector area",
    "success": true
}
```

#### `GET /v1/output` — Collector daily heat output

**Parameters:**
- `collector_area_sqft` (query, required, string) — Collector area in ft² Example: `40`
- `daily_irradiance_btu_sqft` (query, required, string) — Daily irradiance on the collector (BTU/ft²/day) Example: `1800`
- `efficiency_pct` (query, optional, string) — Collector efficiency % (default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarthermal-api/v1/output?collector_area_sqft=40&daily_irradiance_btu_sqft=1800&efficiency_pct=50"
```

**Response:**
```json
{
    "data": {
        "note": "Useful heat = collector area × the daily solar energy hitting it × the collector efficiency (flat-plate ~40–60 %, evacuated tubes higher). A 40 ft² collector under 1,800 BTU/ft²/day at 50 % gives ~36,000 BTU (10.5 kWh) — enough for a family's hot water on a good day. Output drops with cloud, low sun angle and a hotter tank.",
        "inputs": {
            "efficiency_pct": 50,
            "collector_area_sqft": 40,
            "daily_irradiance_btu_sqft": 1800
        },
        "daily_output_btu": 36000,
        "daily_output_kwh": 10.55
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:57.344Z",
        "request_id": "028cd9ad-d65b-41d1-b34d-13c139bd8328"
    },
    "status": "ok",
    "message": "Collector output",
    "success": true
}
```

#### `GET /v1/tank` — Solar storage tank size

**Parameters:**
- `collector_area_sqft` (query, required, string) — Collector area in ft² Example: `40`
- `gallons_per_sqft` (query, optional, string) — Storage gallons per ft² (default 1.5) Example: `1.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarthermal-api/v1/tank?collector_area_sqft=40&gallons_per_sqft=1.5"
```

**Response:**
```json
{
    "data": {
        "note": "Solar storage ≈ 1.5 gallons per square foot of collector (1.5–2 for more cloudy-day carry-over). Too small a tank overheats and stalls the collector on a sunny afternoon; too large never reaches a useful temperature. Size the tank to a day or two of hot-water use and insulate it well.",
        "inputs": {
            "gallons_per_sqft": 1.5,
            "collector_area_sqft": 40
        },
        "storage_gallons": 60
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:57.436Z",
        "request_id": "349df671-d111-4a72-a02f-e4724b3940c6"
    },
    "status": "ok",
    "message": "Tank size",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/solarthermal-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "US units. Output = area × daily irradiance × efficiency; area = (gal × 8.34 × ΔT) ÷ (irradiance × efficiency); tank ≈ 1.5 gal/ft². Estimates — for the local solar resource use a solar-irradiance API; for pool heating use a pool API.",
        "service": "solarthermal-api",
        "endpoints": {
            "GET /v1/area": "Collector area to meet a daily hot-water demand.",
            "GET /v1/meta": "This document.",
            "GET /v1/tank": "Solar storage-tank size from collector area.",
            "GET /v1/output": "Useful daily heat from a collector (area × irradiance × efficiency)."
        },
        "description": "Solar-thermal (solar hot water) maths: collector daily output, the collector area for a hot-water demand, and the storage-tank size."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:57.511Z",
        "request_id": "016613c3-3a72-433e-b764-fd4a2d2ccb6f"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/solarthermal-api
OpenAPI spec: https://www.oanor.com/api/solarthermal-api/openapi.json