# Battery Pack API
> Battery-pack design maths as an API, computed locally and deterministically — the voltage, capacity, energy, current and charge-time numbers an EV, e-bike, solar or robotics pack builder lays out a battery with. The configuration endpoint turns a series-parallel cell layout into the pack: cells in series add their voltages (the series count sets the pack voltage) and cells in parallel add their amp-hours (the parallel count sets the capacity), with the energy in watt-hours = voltage × capacity — a 13S4P pack of 3.6 V / 3.5 Ah cells is 46.8 V, 14 Ah and about 655 Wh from 52 cells, and it also reports the full-charge voltage (series × 4.2 V for Li-ion) to size the charger and BMS. The c-rate endpoint relates current to capacity both ways — give a C-rate to get the current, or a current to get the C-rate — because 1C draws or charges the whole capacity in an hour, so a 14 Ah pack at 2C is 28 A, and it returns the power if you pass the pack voltage. The charge-time endpoint gives the time to charge between two states of charge from the charge current. Everything is computed locally and deterministically, so it is instant and private. Ideal for EV and e-bike builders, solar and off-grid storage tools, robotics and drone packs, and battery-engineering apps. Pure local computation — no key, no third-party service, instant. Pack-design estimates — real cells taper on charge and sag under load. 3 compute endpoints. For runtime under a load use a battery API; for EV charging an EV-charging 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/batterypack-api/..."
```

## Pricing
- **Free** (Free) — 6,900 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 73,000 calls/Mo, 6 req/s
- **Pro** ($31/Mo) — 305,000 calls/Mo, 15 req/s
- **Mega** ($94/Mo) — 1,460,000 calls/Mo, 40 req/s

## Endpoints

### Pack

#### `GET /v1/c-rate` — Current from a C-rate (or C-rate from current)

**Parameters:**
- `capacity_ah` (query, required, string) — Pack capacity (Ah) Example: `14`
- `c_rate` (query, optional, string) — C-rate (give this OR current_a) Example: `2`
- `current_a` (query, optional, string) — Current (A) (give this OR c_rate)
- `pack_voltage` (query, optional, string) — Pack voltage (V) for power Example: `46.8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/batterypack-api/v1/c-rate?capacity_ah=14&c_rate=2&pack_voltage=46.8"
```

**Response:**
```json
{
    "data": {
        "note": "The C-rate scales current to capacity: 1C draws (or charges) the whole capacity in one hour, so a 14 Ah pack at 2C is 28 A and empties in half an hour. Higher C-rates demand cells rated for them and thicker wiring, and they heat the pack and cut its life. Most Li-ion likes ≤1C charging and a few C discharge; LiFePO4 and high-power cells take more.",
        "c_rate": 2,
        "inputs": {
            "c_rate": 2,
            "current_a": null,
            "capacity_ah": 14,
            "pack_voltage": 46.8
        },
        "power_w": 1310.4,
        "current_a": 28
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.771Z",
        "request_id": "824e6517-d01b-44a7-bbd4-faa7b9aa5ac9"
    },
    "status": "ok",
    "message": "C-rate",
    "success": true
}
```

#### `GET /v1/charge-time` — Charge time from capacity and current

**Parameters:**
- `capacity_ah` (query, required, string) — Pack capacity (Ah) Example: `14`
- `charge_current_a` (query, required, string) — Charge current (A) Example: `7`
- `start_pct` (query, optional, string) — Start state of charge % (default 0) Example: `20`
- `target_pct` (query, optional, string) — Target state of charge % (default 100) Example: `100`
- `efficiency_pct` (query, optional, string) — Charge efficiency % (default 100) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/batterypack-api/v1/charge-time?capacity_ah=14&charge_current_a=7&start_pct=20&target_pct=100&efficiency_pct=100"
```

**Response:**
```json
{
    "data": {
        "note": "Charge time ≈ the amp-hours to add ÷ the charge current. It is an ideal figure: Li-ion charges at constant current only up to ~80 %, then tapers in the constant-voltage phase, so the last 20 % takes disproportionately longer — real full charges run noticeably past this estimate. A lower charge current is gentler on the cells and lengthens pack life.",
        "inputs": {
            "start_pct": 20,
            "target_pct": 100,
            "capacity_ah": 14,
            "efficiency_pct": 100,
            "charge_current_a": 7
        },
        "charge_ah": 11.2,
        "charge_time_hours": 1.6,
        "charge_time_minutes": 96
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.851Z",
        "request_id": "ef479439-d637-458f-bb5f-d121d8b0b68f"
    },
    "status": "ok",
    "message": "Charge time",
    "success": true
}
```

#### `GET /v1/configuration` — Pack voltage, capacity and energy

**Parameters:**
- `series_count` (query, required, string) — Cells in series Ns Example: `13`
- `parallel_count` (query, required, string) — Cells in parallel Np Example: `4`
- `cell_capacity_ah` (query, required, string) — Cell capacity (Ah) Example: `3.5`
- `cell_voltage_nominal` (query, optional, string) — Cell nominal voltage (V, default 3.6) Example: `3.6`
- `cell_voltage_max` (query, optional, string) — Cell full-charge voltage (V, default 4.2) Example: `4.2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/batterypack-api/v1/configuration?series_count=13&parallel_count=4&cell_capacity_ah=3.5&cell_voltage_nominal=3.6&cell_voltage_max=4.2"
```

**Response:**
```json
{
    "data": {
        "note": "Cells in series add their voltages (Ns sets the pack voltage); cells in parallel add their capacities (Np sets the amp-hours). Energy in watt-hours = nominal voltage × capacity. A 13S4P pack of 3.6 V / 3.5 Ah cells is 46.8 V, 14 Ah, ~655 Wh. Use the full-charge voltage (Ns × 4.2 V for Li-ion) to size the charger and the BMS.",
        "config": "13S4P",
        "inputs": {
            "series_count": 13,
            "parallel_count": 4,
            "cell_capacity_ah": 3.5,
            "cell_voltage_max": 4.2,
            "cell_voltage_nominal": 3.6
        },
        "total_cells": 52,
        "pack_energy_wh": 655.2,
        "pack_capacity_ah": 14,
        "pack_voltage_full_v": 54.6,
        "pack_voltage_nominal_v": 46.8
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:52.924Z",
        "request_id": "095ffb32-242d-4abc-adf1-ba2d3d681ee3"
    },
    "status": "ok",
    "message": "Pack configuration",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "V, Ah, Wh, A. Pack V = Ns×cell V; Ah = Np×cell Ah; Wh = V×Ah; current = C-rate×Ah. Pack-design estimates — real cells taper on charge and sag under load. For runtime under a load use a battery API; for EV charging an EV-charging API.",
        "service": "batterypack-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/c-rate": "Current from a C-rate, or the C-rate from a current (give one).",
            "GET /v1/charge-time": "Charge time from capacity and charge current.",
            "GET /v1/configuration": "Pack voltage, capacity, energy and cell count from Ns/Np."
        },
        "description": "Battery-pack design maths: pack voltage/capacity/energy from a series-parallel layout, C-rate current, and charge time."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:53.005Z",
        "request_id": "89654c72-a9b5-4771-b808-e3649ca28d1c"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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