# Balloon Decor API
> Party-balloon maths as an API, computed locally and deterministically — the helium-lift and balloon-count numbers a party planner or balloon artist decorates by. The helium endpoint gives a balloon’s lift from its inflated diameter: net lift is the inflated volume times the difference between air and helium density, about 1.046 grams per litre, so a fully inflated 11-inch latex balloon (around 11.4 litres) lifts roughly 12 grams gross and about 9 after its own weight, while a 36-inch giant lifts hundreds of grams. The float endpoint flips it around — how many balloons to float a payload = the weight divided by the net lift per balloon, rounded up, so a 50-gram card floats on six 11-inch balloons. The garland endpoint sizes an organic balloon garland or arch from its length: about 12 balloons per foot in a mix of sizes — roughly 40 % 5-inch, 45 % 11-inch and 15 % 16-inch for that full, textured look — so a 10-foot garland takes about 120 balloons, denser if you want it lush. Everything is computed locally and deterministically, so it is instant and private. Ideal for party-planning, event-decor, balloon-artist and celebration app developers, decor-estimator and shopping-list tools, and event software. Pure local computation — no key, no third-party service, instant. Inches and grams. Live, nothing stored. 3 compute endpoints.

## 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/balloon-api/..."
```

## Pricing
- **Free** (Free) — 7,320 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 59,100 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 240,500 calls/Mo, 15 req/s
- **Mega** ($35/Mo) — 1,372,000 calls/Mo, 40 req/s

## Endpoints

### Balloon

#### `GET /v1/float` — Balloons to float a payload

**Parameters:**
- `payload_g` (query, required, string) — Weight to lift (g) Example: `50`
- `diameter_in` (query, optional, string) — Balloon diameter (default 11) Example: `11`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/balloon-api/v1/float?payload_g=50&diameter_in=11"
```

#### `GET /v1/garland` — Garland balloon count

**Parameters:**
- `length_ft` (query, required, string) — Garland/arch length (ft) Example: `10`
- `balloons_per_foot` (query, optional, string) — Density (default 12) Example: `12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/balloon-api/v1/garland?length_ft=10&balloons_per_foot=12"
```

#### `GET /v1/helium` — Helium lift of a balloon

**Parameters:**
- `diameter_in` (query, required, string) — Inflated diameter (in) Example: `11`
- `balloon_weight_g` (query, optional, string) — Latex weight (g) override

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/balloon-api/v1/helium?diameter_in=11"
```

### Meta

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

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


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