# Energy Cost API
> Electricity cost maths as an API, computed locally and deterministically and entirely currency-agnostic. The cost endpoint works out an appliance's energy use and running cost from its power (watts or kilowatts), the hours used per day and a per-kilowatt-hour tariff — returning the kilowatt-hours and the cost per day, week, month and year, with an optional quantity of identical devices. The compare endpoint pits two appliances against each other: it computes each one's annual energy cost, the saving from the more efficient one, and — given the extra purchase price of the better model — the payback period in years and months. The convert endpoint relates watts, hours and kilowatt-hours: give any two and it returns the third, plus the cost at a tariff. Everything is computed locally and deterministically, so it is instant and private. Kilowatt-hours equal power in kilowatts times hours, and cost equals kilowatt-hours times the rate; months use 365/12 days. Ideal for energy-saving and smart-home apps, appliance comparison and retail tools, sustainability dashboards, and budgeting software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is energy-cost maths; for battery capacity and runtime use a battery 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/energycost-api/..."
```

## Pricing
- **Free** (Free) — 10,635 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 20,250 calls/Mo, 8 req/s
- **Pro** ($32/Mo) — 252,500 calls/Mo, 20 req/s
- **Mega** ($70/Mo) — 1,305,000 calls/Mo, 50 req/s

## Endpoints

### Energy

#### `GET /v1/compare` — Compare two appliances + payback

**Parameters:**
- `power_a` (query, required, string) — Device A power Example: `100`
- `hours_a` (query, required, string) — A hours/day Example: `5`
- `power_b` (query, required, string) — Device B power Example: `60`
- `hours_b` (query, required, string) — B hours/day Example: `5`
- `rate` (query, required, string) — Tariff per kWh Example: `0.30`
- `extra_cost` (query, optional, string) — Extra price of B (for payback)
- `days` (query, optional, string) — Days/year (default 365)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/energycost-api/v1/compare?power_a=100&hours_a=5&power_b=60&hours_b=5&rate=0.30"
```

**Response:**
```json
{
    "data": {
        "note": "Positive annual_saving_with_b means device B costs less to run. Payback uses the extra purchase cost of B ÷ annual saving.",
        "input": {
            "days": 365,
            "extra_cost": 0,
            "rate_per_kwh": 0.3
        },
        "cheaper": "b",
        "device_a": {
            "power_kw": 0.1,
            "annual_kwh": 182.5,
            "annual_cost": 54.75,
            "hours_per_day": 5
        },
        "device_b": {
            "power_kw": 0.06,
            "annual_kwh": 109.5,
            "annual_cost": 32.85,
            "hours_per_day": 5
        },
        "payback_years": null,
        "payback_months": null,
        "annual_saving_with_b": 21.9
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.495Z",
        "request_id": "bd09315c-e754-4b95-8118-5b10c1f3009b"
    },
    "status": "ok",
    "message": "Compare appliances",
    "success": true
}
```

#### `GET /v1/convert` — Watts / hours / kWh / cost

**Parameters:**
- `watts` (query, optional, string) — Power (W) Example: `1500`
- `hours` (query, optional, string) — Hours Example: `2`
- `kwh` (query, optional, string) — Or kWh
- `rate` (query, optional, string) — Tariff per kWh (for cost) Example: `0.25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/energycost-api/v1/convert?watts=1500&hours=2&rate=0.25"
```

**Response:**
```json
{
    "data": {
        "kwh": 3,
        "cost": 0.75,
        "note": "kWh = watts ÷ 1000 × hours. Cost = kWh × rate.",
        "hours": 2,
        "watts": 1500,
        "rate_per_kwh": 0.25
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.593Z",
        "request_id": "8716eb9e-e174-45ed-8dbe-7496e92f53ff"
    },
    "status": "ok",
    "message": "Watts / hours / kWh",
    "success": true
}
```

#### `GET /v1/cost` — Appliance running cost

**Parameters:**
- `power` (query, required, string) — Power Example: `100`
- `power_unit` (query, optional, string) — w|kw (default w) Example: `w`
- `hours_per_day` (query, required, string) — Hours used per day Example: `5`
- `rate` (query, required, string) — Tariff per kWh Example: `0.30`
- `quantity` (query, optional, string) — Number of devices Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/energycost-api/v1/cost?power=100&power_unit=w&hours_per_day=5&rate=0.30&quantity=1"
```

**Response:**
```json
{
    "data": {
        "kwh": {
            "per_day": 0.5,
            "per_week": 3.5,
            "per_year": 182.5,
            "per_month": 15.208
        },
        "cost": {
            "per_day": 0.15,
            "per_week": 1.05,
            "per_year": 54.75,
            "per_month": 4.56
        },
        "note": "kWh = power (kW) × hours. Cost = kWh × rate. Months use 365/12 days.",
        "input": {
            "power_kw": 0.1,
            "quantity": 1,
            "rate_per_kwh": 0.3,
            "hours_per_day": 5
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.694Z",
        "request_id": "28b82b39-0a8a-46f7-bf1d-7ce27af0f845"
    },
    "status": "ok",
    "message": "Running cost",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Currency-agnostic. kWh = power (kW) × hours; cost = kWh × rate. Months use 365/12 days.",
        "service": "energycost",
        "endpoints": {
            "/v1/cost": "Running cost (per day/week/month/year) from power, hours per day and a per-kWh rate.",
            "/v1/compare": "Compare two appliances' running cost and the payback of a more efficient one.",
            "/v1/convert": "Convert between watts, hours and kWh, with optional cost at a tariff."
        },
        "description": "Energy cost maths: appliance running cost, appliance comparison with payback, and energy/power/cost conversion."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.793Z",
        "request_id": "a61bf85c-00fc-492a-8700-7c9da0c56d9a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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