# Hot Air Balloon Lift API
> Hot-air-balloon lift maths as an API, computed locally and deterministically — the thermal-lift, envelope-temperature and air-density numbers a balloon pilot, designer or physics teacher works a flight out with. The lift endpoint gives the buoyant lift from heating the air: gross lift = envelope volume × (outside air density − inside air density), the densities from the ideal-gas law — a 2,500 m³ envelope at 100 °C on a 15 °C day lifts about 698 kg gross, from which you subtract the envelope, basket, burner and fuel for the payload, and the hotter the air and colder the day the more it lifts. The required-temp endpoint inverts it: to carry a target lift the inside air must reach a particular density and so a particular temperature, with a check that it stays under the ~120 °C that nylon envelopes can take — the everyday pre-flight question of whether the balloon can lift today's crew and fuel. The air-density endpoint gives the moist-air density ρ = (P − 0.378·Pv) ÷ (R·T), and explains the counter-intuitive fact that humid air is LESS dense than dry air, slightly cutting the lift. Everything is computed locally and deterministically, so it is instant and private. Ideal for ballooning and aviation tools, STEM and physics-education apps, and buoyancy calculators. Pure local computation — no key, no third-party service, instant. Idealised dry-lift model. 3 compute endpoints. For Archimedes flotation in water use a buoyancy API; for party-balloon helium lift a balloon 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/hotairballoon-api/..."
```

## Pricing
- **Free** (Free) — 9,400 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 91,000 calls/Mo, 6 req/s
- **Pro** ($25/Mo) — 372,000 calls/Mo, 15 req/s
- **Mega** ($77/Mo) — 1,700,000 calls/Mo, 40 req/s

## Endpoints

### Balloon

#### `GET /v1/air-density` — Moist-air density

**Parameters:**
- `temp_c` (query, required, string) — Temperature (°C) Example: `15`
- `pressure_pa` (query, optional, string) — Pressure (Pa, default 101325) Example: `101325`
- `relative_humidity_pct` (query, optional, string) — Relative humidity % (default 0) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hotairballoon-api/v1/air-density?temp_c=15&pressure_pa=101325&relative_humidity_pct=50"
```

#### `GET /v1/lift` — Thermal lift from the temperature difference

**Parameters:**
- `volume_m3` (query, required, string) — Envelope volume (m³) Example: `2500`
- `ambient_temp_c` (query, required, string) — Outside air temperature (°C) Example: `15`
- `internal_temp_c` (query, required, string) — Envelope air temperature (°C) Example: `100`
- `pressure_pa` (query, optional, string) — Air pressure (Pa, default 101325) Example: `101325`
- `envelope_mass_kg` (query, optional, string) — Envelope + basket mass (kg) for payload Example: `250`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hotairballoon-api/v1/lift?volume_m3=2500&ambient_temp_c=15&internal_temp_c=100&pressure_pa=101325&envelope_mass_kg=250"
```

#### `GET /v1/required-temp` — Envelope temperature for a target lift

**Parameters:**
- `volume_m3` (query, required, string) — Envelope volume (m³) Example: `2500`
- `ambient_temp_c` (query, required, string) — Outside air temperature (°C) Example: `15`
- `required_lift_kg` (query, required, string) — Required gross lift (kg) Example: `600`
- `pressure_pa` (query, optional, string) — Air pressure (Pa, default 101325) Example: `101325`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hotairballoon-api/v1/required-temp?volume_m3=2500&ambient_temp_c=15&required_lift_kg=600&pressure_pa=101325"
```

### Meta

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

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


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