# Propane & LPG Tank API
> Propane and LPG tank maths as an API, computed locally and deterministically — the usable-fill, energy and burn-time numbers a homeowner, RV-er, grill-master or HVAC tech works out at the tank. The tank endpoint turns a tank size into real numbers: liquid propane is 4.24 lb per gallon and holds 91,452 BTU per gallon (about 21,569 BTU per pound), so a 20 lb barbecue cylinder carries roughly 4.7 gallons and 431,000 BTU. It knows the two ways tanks are sized — a portable cylinder (20, 30, 40 lb) is rated by the propane weight it holds, while a bulk tank (100, 250, 500, 1000 gal) is filled to only 80 % of its water capacity to leave room for expansion, so a 500-gallon tank actually holds 400 gallons of propane and about 36.6 million BTU. The burntime endpoint divides that energy by an appliance’s BTU-per-hour input rating to give run time: that same 20 lb cylinder runs a 30,000 BTU/hr patio heater about 14 hours, and an optional hours-per-day turns it into days. The refill endpoint costs a fill from a price per gallon, gives the cost per 100,000 BTU so you can compare propane to natural gas or electricity, and — with an appliance rating — the running cost per hour. Everything is computed locally and deterministically, so it is instant and private. Ideal for home-energy, HVAC, RV, off-grid, grilling and outdoor-living app developers, fuel-cost and tank-monitor tools, and propane-delivery calculators. Pure local computation — no key, no third-party service, instant. US units. Live, nothing stored. 3 compute endpoints. For vehicle fuel economy or the ideal gas law use a different 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/propane-api/..."
```

## Pricing
- **Free** (Free) — 7,400 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 54,000 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 225,000 calls/Mo, 15 req/s
- **Mega** ($39/Mo) — 1,310,000 calls/Mo, 40 req/s

## Endpoints

### Propane

#### `GET /v1/burntime` — Appliance run time

**Parameters:**
- `tank_size` (query, required, string) — Tank size Example: `20`
- `appliance_btu` (query, required, string) — Appliance input rating (BTU/hr) Example: `30000`
- `unit` (query, optional, string) — lb or gal Example: `lb`
- `hours_per_day` (query, optional, string) — Hours of use per day (gives run_days) Example: `4`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propane-api/v1/burntime?tank_size=20&appliance_btu=30000&unit=lb&hours_per_day=4"
```

**Response:**
```json
{
    "data": {
        "note": "Run time = total BTU ÷ the appliance's BTU/hr input rating. A 20 lb cylinder (~431,000 BTU) runs a 30,000 BTU/hr patio heater about 14 hours.",
        "inputs": {
            "unit": "lb",
            "tank_size": 20,
            "appliance_btu": 30000
        },
        "run_days": 3.6,
        "run_hours": 14.39,
        "total_btu": 431653,
        "usable_propane_gal": 4.72,
        "propane_gal_per_hour": 0.328
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:06.090Z",
        "request_id": "de265944-b688-4a93-a2b2-e1fa0632e786"
    },
    "status": "ok",
    "message": "Burn time",
    "success": true
}
```

#### `GET /v1/refill` — Refill + operating cost

**Parameters:**
- `tank_size` (query, required, string) — Tank size Example: `500`
- `price_per_gallon` (query, required, string) — Propane price per gallon Example: `3`
- `unit` (query, optional, string) — lb or gal Example: `gal`
- `appliance_btu` (query, optional, string) — Appliance BTU/hr (gives cost/hour) Example: `30000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propane-api/v1/refill?tank_size=500&price_per_gallon=3&unit=gal&appliance_btu=30000"
```

**Response:**
```json
{
    "data": {
        "note": "Fill cost = usable gallons × price per gallon. Cost per 100k BTU lets you compare propane to natural gas or electricity. Pass appliance_btu to also get the running cost per hour.",
        "inputs": {
            "unit": "gal",
            "tank_size": 500,
            "price_per_gallon": 3
        },
        "fill_cost": 1200,
        "run_hours": 1219.36,
        "appliance_btu": 30000,
        "cost_per_hour": 0.9841,
        "cost_per_100k_btu": 3.2804,
        "usable_propane_gal": 400
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:06.184Z",
        "request_id": "6d0204fc-200a-4f9c-9ad6-06d58a9049e4"
    },
    "status": "ok",
    "message": "Refill cost",
    "success": true
}
```

#### `GET /v1/tank` — Usable propane + BTU energy

**Parameters:**
- `tank_size` (query, required, string) — Tank size Example: `20`
- `unit` (query, optional, string) — lb (cylinder weight) or gal (bulk water capacity) Example: `lb`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/propane-api/v1/tank?tank_size=20&unit=lb"
```

**Response:**
```json
{
    "data": {
        "note": "Liquid propane is 4.24 lb/gal and holds 91,452 BTU/gal (21,569 BTU/lb). Portable cylinders are rated by the propane weight they hold; bulk tanks are filled to 80 % of their water capacity to leave room for expansion.",
        "basis": "cylinder rated by propane weight",
        "inputs": {
            "unit": "lb",
            "tank_size": 20
        },
        "total_btu": 431653,
        "usable_propane_lb": 20,
        "usable_propane_gal": 4.72
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:06.284Z",
        "request_id": "96961aaa-d03c-4ff5-83b5-38cdcea2a98f"
    },
    "status": "ok",
    "message": "Tank energy",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units. unit=lb treats tank_size as a cylinder's propane weight (20/30/40 lb); unit=gal treats it as a bulk tank's water capacity, filled to 80 %. 4.24 lb/gal, 91,452 BTU/gal. For vehicle fuel economy or the ideal gas law use a different API.",
        "service": "propane-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/tank": "Usable propane (lb & gal) and total BTU for a cylinder or bulk tank.",
            "GET /v1/refill": "Fill cost and operating cost per hour from a price per gallon.",
            "GET /v1/burntime": "How long a tank runs an appliance of a given BTU/hr rating."
        },
        "description": "Propane / LPG tank maths: usable fill, BTU energy content, appliance burn time, and refill economics."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:06.387Z",
        "request_id": "73f3eeff-b49e-4443-82fb-99e42b652933"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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