# Transformer Ratio API
> Ideal-transformer relations as an API, computed locally and deterministically. The transformer endpoint works from the turns ratio a = Np/Ns = Vp/Vs = Is/Ip: give any ratio-defining pair — the primary and secondary turns, voltages or currents — and it derives the rest, classifies the transformer as step-up, step-down or 1:1 isolation, and reports the primary and secondary apparent power (which are equal for an ideal transformer, so a step-down in voltage is a step-up in current). The power endpoint applies the power balance with an efficiency, Ps = η·Pp, from the primary or secondary power (given directly or as voltage times current) and reports the power loss. The impedance endpoint reflects an impedance across the transformer, Zp/Zs = (Np/Ns)² = a² — the basis of impedance matching, so an 8 Ω speaker on a 10:1 transformer looks like 800 Ω to the source. Everything is computed locally and deterministically, so it is instant and private. Ideal for electrical and electronics-engineering tools, power-supply and audio-amplifier design, impedance-matching and EE-education apps. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is ideal-transformer ratios; for Ohm's law, reactance and series/parallel components use an Ohm's-law 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/transformer-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($75/Mo) — 768,000 calls/Mo, 40 req/s

## Endpoints

### Transformer

#### `GET /v1/impedance` — Impedance transformation

**Parameters:**
- `turns_ratio` (query, optional, string) — Turns ratio a = Np/Ns Example: `10`
- `primary_turns` (query, optional, string) — Or Np
- `secondary_turns` (query, optional, string) — And Ns
- `secondary_impedance` (query, optional, string) — Secondary impedance Zs (Ω) Example: `8`
- `primary_impedance` (query, optional, string) — Or primary impedance Zp (Ω)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transformer-api/v1/impedance?turns_ratio=10&secondary_impedance=8"
```

**Response:**
```json
{
    "data": {
        "formula": "Zp/Zs = (Np/Ns)² = a².",
        "turns_ratio": 10,
        "impedance_ratio": 100,
        "primary_impedance_ohm": 800,
        "secondary_impedance_ohm": 8
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.323Z",
        "request_id": "bd2f87c7-6e48-4b66-bcc6-15d5057153e2"
    },
    "status": "ok",
    "message": "Impedance transformation",
    "success": true
}
```

#### `GET /v1/power` — Power transfer & efficiency

**Parameters:**
- `primary_power` (query, optional, string) — Primary power (W) Example: `1000`
- `primary_voltage` (query, optional, string) — Or Vp
- `primary_current` (query, optional, string) — And Ip
- `secondary_power` (query, optional, string) — Or secondary power (W)
- `efficiency` (query, optional, string) — Efficiency 0–1 (default 1) Example: `0.95`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transformer-api/v1/power?primary_power=1000&efficiency=0.95"
```

**Response:**
```json
{
    "data": {
        "mode": "primary_to_secondary",
        "formula": "Ps = η·Pp; ideal η = 1.",
        "efficiency": 0.95,
        "power_loss_w": 50,
        "primary_power_w": 1000,
        "secondary_power_w": 950
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.417Z",
        "request_id": "f460cd43-d609-41b6-8b37-046d611f8471"
    },
    "status": "ok",
    "message": "Power transfer & efficiency",
    "success": true
}
```

#### `GET /v1/transformer` — Turns ratio & voltage/current

**Parameters:**
- `primary_turns` (query, optional, string) — Primary turns Np Example: `1000`
- `secondary_turns` (query, optional, string) — Secondary turns Ns Example: `100`
- `primary_voltage` (query, optional, string) — Primary voltage Vp Example: `230`
- `secondary_voltage` (query, optional, string) — Secondary voltage Vs
- `primary_current` (query, optional, string) — Primary current Ip
- `secondary_current` (query, optional, string) — Secondary current Is Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transformer-api/v1/transformer?primary_turns=1000&secondary_turns=100&primary_voltage=230&secondary_current=2"
```

**Response:**
```json
{
    "data": {
        "type": "step-down (Vs < Vp)",
        "formula": "a = Np/Ns = Vp/Vs = Is/Ip (ideal transformer).",
        "turns_ratio": 10,
        "primary_turns": 1000,
        "secondary_turns": 100,
        "primary_power_va": 46,
        "primary_current_a": 0.2,
        "primary_voltage_v": 230,
        "turns_ratio_label": "10:1",
        "secondary_power_va": 46,
        "secondary_current_a": 2,
        "secondary_voltage_v": 23
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.511Z",
        "request_id": "f21a60da-eaa8-46c8-9c0d-e7650ca3db3f"
    },
    "status": "ok",
    "message": "Turns ratio & voltage/current",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "transformer",
        "note": "Ideal transformer relations — computed locally and deterministically, no key, no third-party service.",
        "endpoints": [
            "/v1/transformer",
            "/v1/power",
            "/v1/impedance",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:42.629Z",
        "request_id": "e1e9945b-76f9-429c-b171-8d6fb94827bb"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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