# Firewood Calculator API
> Firewood maths as an API, computed locally and deterministically. The volume endpoint turns a wood-stack's length, height and depth (in feet or metres) into its volume in cubic feet and cubic metres, full cords, face cords and steres — a full cord being 128 cubic feet (a 4×4×8 ft stack) and a face cord being an 8×4 ft stack by the piece (log) length. The convert endpoint converts a quantity between cords, face cords, steres, cubic metres and cubic feet, using the piece length for the face-cord relationship. The heat endpoint estimates the heating value of a number of cords by wood species — returning the millions of BTU and the equivalent gallons of heating oil, therms of natural gas and kilowatt-hours — from a built-in table of typical seasoned-wood values (oak, hickory, maple, ash, birch, pine and more) or a custom figure. Everything is computed locally and deterministically, so it is instant and private. Heat values are typical seasoned figures (around 20% moisture) and vary with species, dryness and stove efficiency. Ideal for firewood sellers and delivery tools, heating and homestead apps, and forestry and woodlot calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is firewood volume and energy; for general volume or unit conversion use a unit-conversion 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/firewood-api/..."
```

## Pricing
- **Free** (Free) — 11,035 calls/Mo, 2 req/s
- **Starter** ($13/Mo) — 20,650 calls/Mo, 8 req/s
- **Pro** ($32/Mo) — 256,500 calls/Mo, 20 req/s
- **Mega** ($70/Mo) — 1,325,000 calls/Mo, 50 req/s

## Endpoints

### Firewood

#### `GET /v1/convert` — Convert cord / stere / m³

**Parameters:**
- `value` (query, required, string) — Quantity Example: `1`
- `from` (query, required, string) — cord|facecord|stere|m3|ft3 Example: `cord`
- `piece_length` (query, optional, string) — For face cords (default 16in)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/firewood-api/v1/convert?value=1&from=cord"
```

**Response:**
```json
{
    "data": {
        "note": "Face-cord conversions depend on the piece (log) length; default 16 in.",
        "input": {
            "from": "cord",
            "value": 1,
            "piece_length_ft": 1.3333
        },
        "volume": {
            "cords": 1,
            "steres": 3.6246,
            "cubic_feet": 128,
            "face_cords": 3,
            "cubic_metres": 3.6246
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:18.915Z",
        "request_id": "1168846b-13de-4bb6-b68b-4fadace6a3c8"
    },
    "status": "ok",
    "message": "Cord conversion",
    "success": true
}
```

#### `GET /v1/heat` — Heating value by species

**Parameters:**
- `cords` (query, required, string) — Number of cords Example: `1`
- `species` (query, optional, string) — oakred|hickory|maple|ash|pine|… Example: `oakred`
- `mbtu_per_cord` (query, optional, string) — Or custom MBtu/cord

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/firewood-api/v1/heat?cords=1&species=oakred"
```

**Response:**
```json
{
    "data": {
        "note": "Heat values are typical seasoned-wood figures (≈20% moisture) and vary with species, dryness and stove efficiency.",
        "input": {
            "cords": 1,
            "species": "oakred",
            "mbtu_per_cord": 24.6
        },
        "total_btu": 24600000,
        "equivalent": {
            "kwh": 7209.6,
            "natural_gas_therms": 246,
            "heating_oil_gallons": 177.62
        },
        "total_million_btu": 24.6
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.019Z",
        "request_id": "80fd938a-6ab5-4c66-9c22-a8c1426515e0"
    },
    "status": "ok",
    "message": "Heating value",
    "success": true
}
```

#### `GET /v1/volume` — Stack volume to cords

**Parameters:**
- `length` (query, required, string) — Stack length Example: `8`
- `height` (query, required, string) — Stack height Example: `4`
- `depth` (query, required, string) — Stack depth Example: `4`
- `unit` (query, optional, string) — ft|m (default ft) Example: `ft`
- `piece_length` (query, optional, string) — Log length for face cords (default 16) Example: `16`
- `piece_unit` (query, optional, string) — in|cm|ft|m Example: `in`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/firewood-api/v1/volume?length=8&height=4&depth=4&unit=ft&piece_length=16&piece_unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "1 cord = 128 ft³ (4×4×8 ft). A face cord is 8×4 ft by the piece length (default 16 in). 1 stere = 1 m³.",
        "input": {
            "unit": "ft",
            "depth": 4,
            "height": 4,
            "length": 8,
            "piece_length_ft": 1.3333
        },
        "volume": {
            "cords": 1,
            "steres": 3.6246,
            "cubic_feet": 128,
            "face_cords": 3,
            "cubic_metres": 3.6246
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.103Z",
        "request_id": "d6c6fb3a-91b2-49bb-b368-261936266b53"
    },
    "status": "ok",
    "message": "Stack volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "1 cord = 128 ft³. Face cord = 8×4 ft × piece length (default 16 in). Heat values are typical and vary with moisture.",
        "service": "firewood",
        "species": [
            "osageorange",
            "hickory",
            "blacklocust",
            "oakwhite",
            "oakred",
            "beech",
            "sugarmaple",
            "ash",
            "walnut",
            "birchyellow",
            "redmaple",
            "cherry",
            "elm",
            "douglasfir",
            "sycamore",
            "cedar",
            "pinewhite",
            "poplar",
            "aspen",
            "basswood",
            "spruce",
            "willow"
        ],
        "endpoints": {
            "/v1/heat": "Heating value (million BTU) and heating-oil/gas/kWh equivalents from cords and species.",
            "/v1/volume": "Stack dimensions to cubic feet/metres, cords, face cords and steres.",
            "/v1/convert": "Convert between cord, face cord, stere, m³ and ft³ (face cord uses the piece length)."
        },
        "description": "Firewood maths: stack volume to cords/face cords/steres/m³, unit conversion, and heating value by species."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:19.190Z",
        "request_id": "7d7e8133-ae82-4f4e-b778-84f0255d6e0d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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