# 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"
```

**Response:**
```json
{
    "data": {
        "note": "Balloons needed = payload ÷ net lift per balloon, rounded up. Helium leaks, so floats fade within a day or two — add a few extra and use a balloon treatment (HiFloat) for longevity.",
        "inputs": {
            "payload_g": 50,
            "diameter_in": 11
        },
        "balloons_needed": 6,
        "net_lift_per_balloon_g": 9.15
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:49.742Z",
        "request_id": "5acab8ef-a158-4abd-9980-8c8224cc2ad7"
    },
    "status": "ok",
    "message": "Balloons to float",
    "success": true
}
```

#### `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"
```

**Response:**
```json
{
    "data": {
        "note": "An organic balloon garland uses roughly 12 balloons per foot in a mix of sizes — about 40 % 5\", 45 % 11\" and 15 % 16\" for depth and texture. Denser (16/ft) looks lush; sparser (8/ft) is lighter. Buy ~10 % extra for pops.",
        "inputs": {
            "length_ft": 10,
            "balloons_per_foot": 12
        },
        "size_mix": {
            "5in": 48,
            "11in": 54,
            "16in": 18
        },
        "total_balloons": 120
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:49.845Z",
        "request_id": "cbdad343-c305-4adf-abc0-9dd0e25152db"
    },
    "status": "ok",
    "message": "Garland count",
    "success": true
}
```

#### `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"
```

**Response:**
```json
{
    "data": {
        "note": "Helium lift = inflated volume × (air − helium density) = ~1.046 g per litre. A fully inflated 11\" latex balloon (~11.4 L) lifts about 12 g gross, ~9 g after the balloon's own weight. Net lift floats the string and any attached weight.",
        "inputs": {
            "diameter_in": 11,
            "balloon_weight_g": 2.8
        },
        "net_lift_g": 9.15,
        "gross_lift_g": 11.95,
        "volume_liters": 11.42
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:49.943Z",
        "request_id": "87e3d522-4906-4087-bb41-d58b2e515974"
    },
    "status": "ok",
    "message": "Helium lift",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Diameters in inches, lift in grams. Net helium lift ≈ 1.046 g/L (air 1.225 − helium 0.1786); subtract the latex weight. Garland ≈ 12 balloons/ft. Party planning — helium and temperature vary. For physics buoyancy use a buoyancy API.",
        "service": "balloon-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/float": "Balloons needed to float a payload weight.",
            "GET /v1/helium": "Helium lift (gross & net) of a balloon from its inflated diameter.",
            "GET /v1/garland": "Balloon count and size mix for an organic garland of a given length."
        },
        "description": "Party-balloon maths: helium lift by size, balloons to float a payload, and the balloon count for an arch/garland."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:50.035Z",
        "request_id": "9d95bb03-eeda-40a9-8745-922b671e1d06"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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