# Wood Pellet API
> Wood-pellet heating maths as an API, computed locally and deterministically — the consumption, heat-output and storage numbers a homeowner, installer or heating planner sizes a pellet system by. The consumption endpoint gives the pellets to meet a heat demand = the demand ÷ the usable heat per kilo, where usable = the calorific value × the boiler efficiency: ENplus wood pellets hold about 4.8 kWh/kg and a modern pellet boiler runs ~90 %, so each kilo delivers roughly 4.3 kWh — a 10,000 kWh annual demand then needs about 2.3 tonnes of pellets, around 154 fifteen-kilo bags or a bulk delivery. The heat-output endpoint inverts it: the usable heat from a mass = mass × calorific value × efficiency, so a tonne of ENplus pellets is about 4,800 kWh gross of which a 90 % boiler delivers ~4,320 kWh — the equivalent of roughly 480 litres of heating oil or 432 m³ of natural gas. The storage-volume endpoint sizes the hopper or silo: storage = the pellet mass ÷ the bulk (poured) density, about 650 kg/m³ for ENplus, so 2.3 tonnes fill roughly 3.6 m³ — size the store for the full delivery plus headroom for the fill pipe. Everything is computed locally and deterministically, so it is instant and private. Ideal for pellet-heating and installer tools, home-energy and quoting apps, and renewable-heat calculators. Pure local computation — no key, no third-party service, instant. Uses standard ENplus figures — set your own for a specific pellet grade. 3 compute endpoints. For cordwood use a firewood API; for propane/LPG a propane 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/pellet-api/..."
```

## Pricing
- **Free** (Free) — 7,350 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 61,500 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 249,000 calls/Mo, 15 req/s
- **Mega** ($76/Mo) — 1,155,000 calls/Mo, 40 req/s

## Endpoints

### Pellet

#### `GET /v1/consumption` — Pellets for a heat demand

**Parameters:**
- `heat_demand_kwh` (query, required, string) — Annual/period heat demand (kWh) Example: `10000`
- `calorific_value_kwh_kg` (query, optional, string) — Calorific value (kWh/kg, default 4.8) Example: `4.8`
- `efficiency_pct` (query, optional, string) — Boiler efficiency (%, default 90) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pellet-api/v1/consumption?heat_demand_kwh=10000&calorific_value_kwh_kg=4.8&efficiency_pct=90"
```

**Response:**
```json
{
    "data": {
        "note": "The pellets to meet a heat demand = the demand ÷ the usable heat per kilo, where usable = the calorific value × the boiler efficiency. ENplus wood pellets hold about 4.8 kWh/kg, and a modern pellet boiler runs ~90 %, so each kilo delivers ~4.3 kWh of heat. A 10,000 kWh annual demand then needs about 2.3 tonnes of pellets — roughly 154 fifteen-kilo bags, or a bulk delivery.",
        "inputs": {
            "efficiency_pct": 90,
            "heat_demand_kwh": 10000,
            "calorific_value_kwh_kg": 4.8
        },
        "bags_15kg": 155,
        "pellet_kg": 2314.81,
        "pellet_tonnes": 2.3148,
        "usable_kwh_per_kg": 4.32
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:48.522Z",
        "request_id": "b14840cb-679d-4c1a-80a0-532ae7340bfa"
    },
    "status": "ok",
    "message": "Consumption",
    "success": true
}
```

#### `GET /v1/heat-output` — Usable heat from pellets

**Parameters:**
- `pellet_kg` (query, required, string) — Pellet mass (kg) Example: `2314.81`
- `calorific_value_kwh_kg` (query, optional, string) — Calorific value (kWh/kg, default 4.8) Example: `4.8`
- `efficiency_pct` (query, optional, string) — Boiler efficiency (%, default 90) Example: `90`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pellet-api/v1/heat-output?pellet_kg=2314.81&calorific_value_kwh_kg=4.8&efficiency_pct=90"
```

**Response:**
```json
{
    "data": {
        "note": "The usable heat from a quantity of pellets = the mass × the calorific value × the boiler efficiency. 1 tonne of ENplus pellets is about 4,800 kWh of gross energy, of which a 90 % boiler delivers ~4,320 kWh to the house — the equivalent of roughly 480 litres of heating oil or 432 m³ of natural gas. The rest goes up the flue as losses, which is why efficiency and clean burning matter.",
        "inputs": {
            "pellet_kg": 2314.81,
            "efficiency_pct": 90,
            "calorific_value_kwh_kg": 4.8
        },
        "usable_heat_kwh": 9999.98,
        "gross_energy_kwh": 11111.09
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:48.639Z",
        "request_id": "d854cb1e-dfff-407c-a927-a37abab5aca7"
    },
    "status": "ok",
    "message": "Heat output",
    "success": true
}
```

#### `GET /v1/storage-volume` — Storage volume from mass

**Parameters:**
- `pellet_kg` (query, required, string) — Pellet mass (kg) Example: `2314.81`
- `bulk_density_kg_m3` (query, optional, string) — Bulk density (kg/m³, default 650) Example: `650`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pellet-api/v1/storage-volume?pellet_kg=2314.81&bulk_density_kg_m3=650"
```

**Response:**
```json
{
    "data": {
        "note": "Storage = the pellet mass ÷ the bulk (poured) density, about 650 kg/m³ for ENplus pellets. So 2.3 tonnes of a year's pellets fill roughly 3.6 m³ — size a hopper or silo room for the full delivery plus headroom for the fill pipe and a margin, since a bulk blower needs space to settle the pellets without crushing them to dust.",
        "inputs": {
            "pellet_kg": 2314.81,
            "bulk_density_kg_m3": 650
        },
        "storage_litres": 3561.2,
        "storage_volume_m3": 3.561
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:48.740Z",
        "request_id": "f68434f4-5404-4cc5-8ffa-9a2b717cb0b2"
    },
    "status": "ok",
    "message": "Storage volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "kWh, kg, m³. ENplus ~4.8 kWh/kg, bulk ~650 kg/m³. pellets = demand/(cv·eff); heat = kg·cv·eff; volume = kg/density. For cordwood use a firewood API; for propane/LPG a propane API.",
        "service": "pellet-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/consumption": "Pellet mass (and bags) to cover a heat demand.",
            "GET /v1/heat-output": "Gross and usable heat from a mass of pellets.",
            "GET /v1/storage-volume": "Storage volume from pellet mass and bulk density."
        },
        "description": "Wood-pellet heating maths: pellet mass for a heat demand, usable heat from a mass, and storage volume."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:48.844Z",
        "request_id": "b9c4671b-5520-4f55-a8ee-ad54be7edcaf"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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