# HVAC Ductwork API
> HVAC duct-sizing maths as an API, computed locally and deterministically — the duct dimensions an installer or designer sizes a system with so the air moves quietly and efficiently. The round-duct endpoint gives the round duct for an airflow at a target velocity: area = airflow ÷ velocity (CFM ÷ ft/min = ft²), then diameter = √(4·area/π) — 400 CFM at a 700 fpm trunk velocity wants about a 10.2-inch round, rounded up to the next 12-inch trade size. The velocity endpoint gives the air speed inside a duct from the airflow and its size, round or rectangular — 400 CFM through a 12 × 8 duct runs at 600 fpm, comfortably quiet, while the same air in a 10-inch round moves at 733 fpm. The equivalent endpoint gives the equivalent round diameter of a rectangular duct by the ASHRAE relation De = 1.30 · (a·b)^0.625 ÷ (a+b)^0.25, so a 12 × 8 rectangular carries the same air at the same friction as a 10.7-inch round — letting you size on a round friction chart and convert to fit the space. Everything is computed locally and deterministically, so it is instant and private. Ideal for HVAC-design and installer apps, duct-sizing and takeoff tools, building-services calculators, and trade-school aids. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For room air changes use a ventilation API; for the cooling/heating load use an HVAC 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/ductwork-api/..."
```

## Pricing
- **Free** (Free) — 450 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 12,000 calls/Mo, 6 req/s
- **Pro** ($18/Mo) — 78,000 calls/Mo, 15 req/s
- **Mega** ($53/Mo) — 255,000 calls/Mo, 36 req/s

## Endpoints

### Ductwork

#### `GET /v1/equivalent` — Equivalent round diameter

**Parameters:**
- `width_in` (query, required, string) — Rectangular width in inches Example: `12`
- `height_in` (query, required, string) — Rectangular height in inches Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ductwork-api/v1/equivalent?width_in=12&height_in=8"
```

**Response:**
```json
{
    "data": {
        "note": "The equivalent round diameter carries the same airflow at the same friction loss: De = 1.30 · (a·b)^0.625 ÷ (a+b)^0.25 (ASHRAE). It lets you size on a round-duct friction chart, then convert to a rectangular duct that fits the space — note a square duct moves more air than a flat one of the same area.",
        "inputs": {
            "width_in": 12,
            "height_in": 8
        },
        "next_standard_in": 12,
        "equivalent_diameter_in": 10.66
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:41.017Z",
        "request_id": "af74b342-2fae-4ed4-832c-a755f268e1c6"
    },
    "status": "ok",
    "message": "Equivalent diameter",
    "success": true
}
```

#### `GET /v1/round-duct` — Round duct for an airflow

**Parameters:**
- `cfm` (query, required, string) — Airflow in CFM Example: `400`
- `velocity_fpm` (query, required, string) — Target velocity in ft/min Example: `700`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ductwork-api/v1/round-duct?cfm=400&velocity_fpm=700"
```

**Response:**
```json
{
    "data": {
        "note": "Duct area = airflow ÷ velocity (CFM ÷ ft/min = ft²), then diameter = √(4·area/π). Typical design velocities are ~700–900 fpm for residential supply trunks, lower for returns and near rooms to stay quiet. Round up to the next trade size — a slightly larger duct is quieter and lower-resistance.",
        "inputs": {
            "cfm": 400,
            "velocity_fpm": 700
        },
        "area_sqft": 0.5714,
        "diameter_in": 10.24,
        "next_standard_in": 12
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:41.111Z",
        "request_id": "87123ea2-2809-49c3-a0a2-478a7f05405e"
    },
    "status": "ok",
    "message": "Round duct",
    "success": true
}
```

#### `GET /v1/velocity` — Air velocity inside a duct

**Parameters:**
- `cfm` (query, required, string) — Airflow in CFM Example: `400`
- `diameter_in` (query, optional, string) — Round duct diameter in inches Example: `10`
- `width_in` (query, optional, string) — Rectangular width in inches Example: `12`
- `height_in` (query, optional, string) — Rectangular height in inches Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/ductwork-api/v1/velocity?cfm=400&diameter_in=10&width_in=12&height_in=8"
```

**Response:**
```json
{
    "data": {
        "note": "Velocity = airflow ÷ cross-sectional area. Keep it under ~900 fpm in supply trunks and ~600 in branches near living spaces, or the system gets noisy; too low and ducts get bulky. Pass a diameter for a round duct, or width and height for a rectangular one.",
        "inputs": {
            "cfm": 400,
            "shape": "round"
        },
        "area_sqft": 0.5454,
        "velocity_fpm": 733
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:41.170Z",
        "request_id": "2599b1d4-02a3-418b-b30a-81edeef3ded6"
    },
    "status": "ok",
    "message": "Velocity",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (CFM, inches, ft/min). area = CFM/velocity; velocity = CFM/area; De = 1.30·(a·b)^0.625/(a+b)^0.25. Estimates — for room air changes use a ventilation API, for the cooling/heating load use an HVAC API.",
        "service": "ductwork-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/velocity": "Air velocity inside a round or rectangular duct.",
            "GET /v1/equivalent": "Equivalent round diameter of a rectangular duct (ASHRAE).",
            "GET /v1/round-duct": "Round duct diameter for an airflow at a target velocity."
        },
        "description": "HVAC duct-sizing maths: round duct for an airflow at a velocity, air velocity inside a duct, and the equivalent round diameter of a rectangular duct."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:41.239Z",
        "request_id": "09e52eb4-f0b1-4950-a2cb-95ae75437821"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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