# Butterworth Filter API
> Butterworth-filter design maths as an API, computed locally and deterministically. The order endpoint computes the minimum filter order needed to meet a specification — from the passband edge frequency and its allowed ripple and the stopband edge frequency and its required attenuation it returns the exact and rounded-up order, n = ⌈log10((10^(As/10)−1)/(10^(Ap/10)−1)) / (2·log10(fs/fp))⌉, where each extra order adds 20 dB per decade of roll-off. The response endpoint computes the maximally-flat magnitude response of an n-th order Butterworth filter at a frequency, |H| = 1/√(1 + (f/fc)^(2n)), in linear and decibel form with the attenuation and the asymptotic roll-off — the response is exactly −3.01 dB at the cutoff for any order. The poles endpoint gives the s-plane pole locations, equally spaced on a circle of radius ωc in the left half-plane at angles π·(2k+n−1)/(2n), all stable. Frequencies are in hertz (or any consistent unit), ripple and attenuation in decibels and the order a positive integer. Everything is computed locally and deterministically, so it is instant and private. Ideal for DSP, audio, RF, instrumentation and embedded app developers, anti-aliasing and filter-design tools, and signal-processing education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is the Butterworth filter; for a single-pole RC cutoff and resonance use a resonance API and for AC impedance an impedance 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/butterworth-api/..."
```

## Pricing
- **Free** (Free) — 2,900 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 40,000 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($72/Mo) — 1,690,000 calls/Mo, 40 req/s

## Endpoints

### Butterworth

#### `GET /v1/order` — Minimum filter order

**Parameters:**
- `passband_edge` (query, required, string) — Passband edge (Hz) Example: `1000`
- `stopband_edge` (query, required, string) — Stopband edge (Hz) Example: `4000`
- `passband_ripple` (query, required, string) — Passband ripple Ap (dB) Example: `1`
- `stopband_attenuation` (query, required, string) — Stopband attenuation As (dB) Example: `40`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/butterworth-api/v1/order?passband_edge=1000&stopband_edge=4000&passband_ripple=1&stopband_attenuation=40"
```

**Response:**
```json
{
    "data": {
        "note": "Minimum Butterworth order n = ⌈log10((10^(As/10)−1)/(10^(Ap/10)−1)) / (2·log10(fs/fp))⌉. Each extra order adds 20 dB/decade of roll-off.",
        "order": 4,
        "inputs": {
            "passband_edge": 1000,
            "stopband_edge": 4000,
            "passband_ripple": 1,
            "stopband_attenuation": 40
        },
        "exact_order": 3.80924
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:22.952Z",
        "request_id": "2e025c7a-774a-48e2-b446-fdb32c5fa507"
    },
    "status": "ok",
    "message": "Filter order",
    "success": true
}
```

#### `GET /v1/poles` — Pole locations

**Parameters:**
- `order` (query, required, string) — Filter order n Example: `4`
- `cutoff` (query, optional, string) — Cutoff ωc (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/butterworth-api/v1/poles?order=4&cutoff=1"
```

**Response:**
```json
{
    "data": {
        "note": "Butterworth poles lie equally spaced on a circle of radius ωc in the left half of the s-plane, at angles π·(2k+n−1)/(2n). They are all stable (negative real part).",
        "poles": [
            {
                "imag": 0.92387953,
                "real": -0.38268343,
                "angle_deg": 112.5
            },
            {
                "imag": 0.38268343,
                "real": -0.92387953,
                "angle_deg": 157.5
            },
            {
                "imag": -0.38268343,
                "real": -0.92387953,
                "angle_deg": 202.5
            },
            {
                "imag": -0.92387953,
                "real": -0.38268343,
                "angle_deg": 247.5
            }
        ],
        "inputs": {
            "order": 4,
            "cutoff": 1
        }
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:23.019Z",
        "request_id": "f878f0e9-5fe0-4ce5-bc85-2747919f173a"
    },
    "status": "ok",
    "message": "Pole locations",
    "success": true
}
```

#### `GET /v1/response` — Magnitude response

**Parameters:**
- `order` (query, required, string) — Filter order n Example: `4`
- `frequency` (query, required, string) — Frequency (Hz) Example: `2000`
- `cutoff` (query, required, string) — Cutoff frequency fc (Hz) Example: `1000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/butterworth-api/v1/response?order=4&frequency=2000&cutoff=1000"
```

**Response:**
```json
{
    "data": {
        "note": "Magnitude |H| = 1/√(1 + (f/fc)^(2n)). At fc the response is exactly −3.01 dB for any order; far above fc the roll-off is 20·n dB/decade.",
        "inputs": {
            "order": 4,
            "cutoff": 1000,
            "frequency": 2000
        },
        "magnitude": 0.06237829,
        "magnitude_db": -24.099331,
        "attenuation_db": 24.099331,
        "rolloff_db_per_decade": 80
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:23.109Z",
        "request_id": "2bd76ec6-7285-4ccb-8cce-30bb6d421aa0"
    },
    "status": "ok",
    "message": "Magnitude response",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Frequencies in Hz (or any consistent unit), attenuations and ripple in dB, order a positive integer. The Butterworth response is maximally flat in the passband with no ripple.",
        "service": "butterworth-api",
        "formulae": {
            "order": "n = ⌈log10((10^(As/10)−1)/(10^(Ap/10)−1)) / (2·log10(fs/fp))⌉",
            "poles": "s_k = ωc·exp(jπ(2k+n−1)/(2n))",
            "response": "|H| = 1/√(1 + (f/fc)^(2n))"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/order": "Minimum filter order from passband/stopband edges and attenuations.",
            "GET /v1/poles": "Left-half-plane pole locations of an n-th order Butterworth.",
            "GET /v1/response": "Magnitude (and dB) of an n-th order Butterworth at a frequency."
        },
        "description": "Butterworth filter calculator: the minimum order for a specification, the maximally-flat magnitude response, and the s-plane pole locations."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:23.183Z",
        "request_id": "900424a0-3bdc-493e-b7fc-2888a98067ec"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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