# Ice Cream API
> Ice-cream and gelato batch maths as an API, computed locally and deterministically — the overrun, yield and solids numbers a gelatiere, ice-cream maker or production planner balances a mix by. The overrun endpoint measures the air whipped into the mix during freezing by the weight method: from the same container filled first with mix and then with frozen ice cream, overrun = (mix weight − frozen weight) ÷ frozen weight × 100 — a cup that drops from 1000 g to 625 g ran 60 % overrun. Dense gelato sits around 20–35 %, premium ice cream 25–50 %, soft-serve and economy tubs 50–100 %+; more air means a lighter, cheaper, faster-melting product. The yield endpoint turns a mix volume and an overrun into the frozen volume (mix × (1 + overrun/100)) and the number of scoops at a given scoop size, so 2 litres of mix at 60 % overrun yields 3.2 litres and about 53 sixty-millilitre scoops — which is why overrun is a direct cost lever. The total-solids endpoint balances a recipe: total solids (sugar + fat + milk-solids-not-fat + other) as a percent of the mix weight, with the fat, sugar, MSNF and water percentages — a typical ice cream runs 36–42 % total solids, gelato lower in fat, and balancing solids against water is what keeps the texture smooth rather than icy. Everything is computed locally and deterministically, so it is instant and private. Ideal for gelateria and creamery tools, recipe-balancing apps, and food-production calculators. Pure local computation — no key, no third-party service, instant. 3 compute endpoints. For general cooking measure conversions use a cooking 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/icecream-api/..."
```

## Pricing
- **Free** (Free) — 6,600 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 57,000 calls/Mo, 6 req/s
- **Pro** ($23/Mo) — 242,000 calls/Mo, 15 req/s
- **Mega** ($73/Mo) — 1,120,000 calls/Mo, 40 req/s

## Endpoints

### IceCream

#### `GET /v1/overrun` — Overrun from mix and frozen weights

**Parameters:**
- `mix_weight_g` (query, required, string) — Mix weight in the container (g) Example: `1000`
- `frozen_weight_g` (query, required, string) — Frozen weight, same container (g) Example: `625`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/icecream-api/v1/overrun?mix_weight_g=1000&frozen_weight_g=625"
```

#### `GET /v1/total-solids` — Total-solids balance of a mix

**Parameters:**
- `water_g` (query, optional, string) — Water (g) Example: `600`
- `sugar_g` (query, optional, string) — Sugar (g) Example: `200`
- `fat_g` (query, optional, string) — Fat (g) Example: `100`
- `msnf_g` (query, optional, string) — Milk solids-not-fat (g) Example: `90`
- `other_solids_g` (query, optional, string) — Other solids (g) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/icecream-api/v1/total-solids?water_g=600&sugar_g=200&fat_g=100&msnf_g=90&other_solids_g=10"
```

#### `GET /v1/yield` — Frozen volume and scoops

**Parameters:**
- `mix_volume_ml` (query, required, string) — Mix volume (ml) Example: `2000`
- `overrun_pct` (query, required, string) — Overrun (%) Example: `60`
- `scoop_ml` (query, optional, string) — Scoop size (ml, default 60) Example: `60`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/icecream-api/v1/yield?mix_volume_ml=2000&overrun_pct=60&scoop_ml=60"
```

### Meta

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

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


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