# Heat Pump COP API
> Heat-pump and refrigeration performance maths as an API, computed locally and deterministically — the efficiency numbers an HVAC engineer, energy auditor or heat-pump installer actually works with. The cop endpoint gives the coefficient of performance and the US EER rating from the thermal capacity and the electrical power: a unit moving 7 kW of heat on 2 kW of electricity has a COP of 3.5 (an EER of 12), meaning 3.5 units of heating or cooling for every unit of electricity — which is why a heat pump beats resistance heating, where the COP is exactly 1. The carnot endpoint gives the unbeatable ideal limit set only by the absolute temperatures — heating = Th ÷ (Th − Tc), cooling = Tc ÷ (Th − Tc) in kelvin, where heating COP always equals cooling COP plus one — and, given a real COP, the second-law efficiency that says how close the machine runs to that ceiling; the smaller the temperature lift, the higher the limit, which is why ground-source and low-temperature systems beat air-source on a cold day. The capacity endpoint turns electrical power and a COP into the delivered heating or cooling in kilowatts, BTU per hour and tons of refrigeration — the extra energy over the electricity is pulled from the outside air, ground or water. Everything is computed locally and deterministically, so it is instant and private. Ideal for HVAC and refrigeration engineers, energy auditors, heat-pump and building-performance tools, and sustainability dashboards. Pure local computation — no key, no third-party service, instant. Estimates at the stated conditions — real COP falls as the temperature lift rises. 3 compute endpoints. For room sizing use an HVAC BTU API; for moist-air properties use a psychrometric 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/heatpump-api/..."
```

## Pricing
- **Free** (Free) — 5,900 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 66,000 calls/Mo, 6 req/s
- **Pro** ($37/Mo) — 272,000 calls/Mo, 15 req/s
- **Mega** ($112/Mo) — 1,340,000 calls/Mo, 40 req/s

## Endpoints

### Performance

#### `GET /v1/capacity` — Delivered capacity from power and COP

**Parameters:**
- `power_input_kw` (query, required, string) — Electrical power input (kW) Example: `2`
- `cop` (query, required, string) — Coefficient of performance Example: `3.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/heatpump-api/v1/capacity?power_input_kw=2&cop=3.5"
```

**Response:**
```json
{
    "data": {
        "note": "Delivered heat (or cooling) = the electrical power × the COP. A 2 kW compressor at a COP of 3.5 moves 7 kW of heat — about 23,900 BTU/hr or 2 tons. The electricity is not 'lost': the extra energy is pulled from the outdoor air, ground or water, which is the whole point of a heat pump over a resistance heater.",
        "inputs": {
            "cop": 3.5,
            "power_input_kw": 2
        },
        "capacity_kw": 7,
        "capacity_tons": 1.99,
        "capacity_btu_hr": 23885
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:55.458Z",
        "request_id": "0b4a7625-793a-4872-81a6-5c8f591b991e"
    },
    "status": "ok",
    "message": "Capacity",
    "success": true
}
```

#### `GET /v1/carnot` — Ideal (Carnot) COP and second-law efficiency

**Parameters:**
- `hot_temp_c` (query, required, string) — Warm-side temperature (°C) Example: `20`
- `cold_temp_c` (query, required, string) — Cold-side temperature (°C) Example: `0`
- `mode` (query, optional, string) — heating or cooling (default heating) Example: `heating`
- `actual_cop` (query, optional, string) — Real COP to grade against the limit

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/heatpump-api/v1/carnot?hot_temp_c=20&cold_temp_c=0&mode=heating"
```

**Response:**
```json
{
    "data": {
        "note": "The Carnot COP is the unbeatable ceiling set only by the absolute temperatures: heating = Th ÷ (Th − Tc), cooling = Tc ÷ (Th − Tc), with T in kelvin (and heating COP always equals cooling COP + 1). The smaller the temperature lift, the higher the ceiling — which is why ground-source and low-temperature underfloor systems outperform air-source on a cold day.",
        "inputs": {
            "mode": "heating",
            "hot_temp_c": 20,
            "cold_temp_c": 0
        },
        "carnot_cop": 14.66,
        "carnot_cop_cooling": 13.66,
        "carnot_cop_heating": 14.66,
        "temperature_lift_c": 20
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:55.554Z",
        "request_id": "399e0579-da6a-43dd-ab48-b96ac3e5aef7"
    },
    "status": "ok",
    "message": "Carnot COP",
    "success": true
}
```

#### `GET /v1/cop` — COP and EER from capacity and power

**Parameters:**
- `capacity_kw` (query, required, string) — Thermal capacity, heating or cooling (kW) Example: `7.034`
- `power_input_kw` (query, required, string) — Electrical power input (kW) Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/heatpump-api/v1/cop?capacity_kw=7.034&power_input_kw=2"
```

**Response:**
```json
{
    "data": {
        "cop": 3.52,
        "note": "COP = the heat moved ÷ the electrical power, in the same units — a COP of 3.5 means 3.5 kW of heating or cooling for every 1 kW of electricity, which is why heat pumps beat resistance heating (COP = 1). EER is the same thing in Btu per watt-hour (COP × 3.412), the US cooling rating. Both fall as the temperature lift grows, so a quoted COP only holds at its rating conditions.",
        "inputs": {
            "capacity_kw": 7.034,
            "power_input_kw": 2
        },
        "capacity_tons": 2,
        "eer_btu_per_wh": 12,
        "capacity_btu_hr": 24001
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:55.638Z",
        "request_id": "e3687876-2cd4-45d5-a72b-64680c6a6e91"
    },
    "status": "ok",
    "message": "COP / EER",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "kW (power/thermal), °C, plus BTU/hr and tons. COP = capacity ÷ power; EER = COP × 3.412; Carnot heating = Th/(Th−Tc), cooling = Tc/(Th−Tc) (kelvin). Estimates at the stated conditions. For room sizing use an HVAC API; for moist air a psychrometric API.",
        "service": "heatpump-api",
        "endpoints": {
            "GET /v1/cop": "COP and EER from the thermal capacity and electrical power.",
            "GET /v1/meta": "This document.",
            "GET /v1/carnot": "Ideal (Carnot) COP from the source/sink temperatures, with second-law efficiency.",
            "GET /v1/capacity": "Delivered thermal capacity from power and COP."
        },
        "description": "Heat-pump / refrigeration performance maths: COP and EER from capacity and power, the Carnot limit from temperatures, and the delivered capacity from power and COP."
    },
    "meta": {
        "timestamp": "2026-06-06T23:53:55.729Z",
        "request_id": "0d722c74-6575-4a46-b787-1c6b9c40b9bf"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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