# Battery Calculator API
> Battery and accumulator maths as an API, computed locally and deterministically from basic electrical relationships. The runtime endpoint estimates how long a battery will last under a given load — from the capacity (in mAh, Ah or Wh) and the load (in watts, or amps at a voltage), with adjustable depth-of-discharge and conversion efficiency — and reports the usable energy and the runtime in hours and minutes. The capacity endpoint converts a battery capacity between milliamp-hours, amp-hours, watt-hours, kilowatt-hours and joules at a given voltage. The pack endpoint builds a series/parallel cell pack (for example 3S2P): it returns the pack voltage, capacity and energy and the total cell count — series adds voltage, parallel adds capacity. The charge endpoint estimates the charge time from the capacity and the charge current (or a C-rate), with a charge efficiency and an optional from/to state-of-charge window. Everything is computed locally and deterministically, so it is instant and private. Real-world figures depend on temperature, age, C-rate and the discharge curve, so treat the results as estimates. Ideal for consumer-electronics and IoT tools, solar and off-grid sizing, drone and RC planning, UPS and backup-power sizing, and EV and battery-pack design. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is battery maths; for Ohm's-law voltage/current/resistance use an electronics 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/battery-api/..."
```

## Pricing
- **Free** (Free) — 9,535 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 19,150 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 241,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,250,000 calls/Mo, 50 req/s

## Endpoints

### Battery

#### `GET /v1/capacity` — Convert mAh / Ah / Wh / kWh / J

**Parameters:**
- `voltage` (query, required, string) — Volts Example: `3.7`
- `mah` (query, optional, string) — mAh Example: `3000`
- `ah` (query, optional, string) — Or Ah
- `wh` (query, optional, string) — Or Wh

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/battery-api/v1/capacity?voltage=3.7&mah=3000"
```

**Response:**
```json
{
    "data": {
        "ah": 3,
        "wh": 11.1,
        "kwh": 0.0111,
        "mah": 3000,
        "note": "Wh = (mAh ÷ 1000) × V. Energy in joules = Wh × 3600.",
        "input": {
            "voltage": 3.7
        },
        "joules": 39960
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.752Z",
        "request_id": "31a9d479-5fa0-4275-9854-99ed54c378b9"
    },
    "status": "ok",
    "message": "Capacity conversion",
    "success": true
}
```

#### `GET /v1/charge` — Charge time

**Parameters:**
- `mah` (query, optional, string) — Capacity mAh (or ah) Example: `3000`
- `charge_ma` (query, optional, string) — Charge current mA Example: `1500`
- `charge_a` (query, optional, string) — Or charge amps
- `c_rate` (query, optional, string) — Or C-rate
- `efficiency` (query, optional, string) — 0-1 (default 0.9)
- `from_percent` (query, optional, string) — Start SOC % Example: `0`
- `to_percent` (query, optional, string) — Target SOC % Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/battery-api/v1/charge?mah=3000&charge_ma=1500&from_percent=0&to_percent=100"
```

**Response:**
```json
{
    "data": {
        "note": "Approx CC charge time = charge mAh ÷ charge current ÷ efficiency. Real Li-ion charging slows in the CV phase near full.",
        "input": {
            "mah": 3000,
            "charge_ma": 1500,
            "efficiency": 0.9,
            "to_percent": 100,
            "from_percent": 0
        },
        "c_rate": 0.5,
        "charge_mah": 3000,
        "charge_time": "2h 13m",
        "charge_hours": 2.222,
        "charge_minutes": 133.3
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.862Z",
        "request_id": "7312a652-5cab-4cc5-9d93-87e7c2d20c6e"
    },
    "status": "ok",
    "message": "Charge time",
    "success": true
}
```

#### `GET /v1/pack` — Series/parallel pack

**Parameters:**
- `series` (query, required, string) — Cells in series (S) Example: `3`
- `parallel` (query, required, string) — Strings in parallel (P) Example: `2`
- `cell_voltage` (query, required, string) — Cell voltage Example: `3.7`
- `cell_mah` (query, required, string) — Cell capacity mAh Example: `2500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/battery-api/v1/pack?series=3&parallel=2&cell_voltage=3.7&cell_mah=2500"
```

**Response:**
```json
{
    "data": {
        "note": "Series adds voltage; parallel adds capacity. Pack Wh = pack V × pack Ah.",
        "input": {
            "series": 3,
            "cell_mah": 2500,
            "parallel": 2,
            "cell_voltage": 3.7
        },
        "pack_ah": 5,
        "pack_wh": 55.5,
        "pack_mah": 5000,
        "cells_total": 6,
        "pack_voltage": 11.1,
        "configuration": "3S2P"
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.943Z",
        "request_id": "54db31de-59ae-4fc7-91d7-9620062e3440"
    },
    "status": "ok",
    "message": "Series/parallel pack",
    "success": true
}
```

#### `GET /v1/runtime` — Battery runtime under load

**Parameters:**
- `wh` (query, optional, string) — Capacity Wh (or mah/ah+voltage)
- `mah` (query, optional, string) — Capacity mAh
- `ah` (query, optional, string) — Capacity Ah Example: `100`
- `voltage` (query, optional, string) — Volts (for mah/ah or amps) Example: `12`
- `watts` (query, optional, string) — Load in watts Example: `100`
- `amps` (query, optional, string) — Or load in amps
- `depth_of_discharge` (query, optional, string) — 0-1 (default 1)
- `efficiency` (query, optional, string) — 0-1 (default 1)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/battery-api/v1/runtime?ah=100&voltage=12&watts=100"
```

**Response:**
```json
{
    "data": {
        "note": "Runtime = usable energy ÷ load. Usable energy = capacity × depth-of-discharge × efficiency. Real runtime drops under high C-rate, cold and age.",
        "input": {
            "load_w": 100,
            "stored_wh": 1200,
            "efficiency": 1,
            "depth_of_discharge": 1
        },
        "runtime": "12h",
        "usable_wh": 1200,
        "runtime_hours": 12,
        "runtime_minutes": 720
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.045Z",
        "request_id": "a78bbd94-ea92-4dc4-8970-eedd534bd6ef"
    },
    "status": "ok",
    "message": "Battery runtime",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Estimates only — real figures vary with temperature, age, C-rate and discharge curve.",
        "service": "battery",
        "endpoints": {
            "/v1/pack": "Build a series/parallel pack: voltage, capacity, energy and cell count.",
            "/v1/charge": "Estimate charge time from capacity and charge current (or C-rate).",
            "/v1/runtime": "Estimate runtime from capacity and load, with depth-of-discharge and efficiency.",
            "/v1/capacity": "Convert capacity between mAh, Ah, Wh, kWh and joules (with voltage)."
        },
        "description": "Battery maths: runtime, mAh/Wh capacity conversion, series/parallel pack building and charge time."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.147Z",
        "request_id": "ae0a4ee7-0da0-42cd-80e2-2c0d7ad1f65d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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