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

**Response:**
```json
{
    "data": {
        "note": "Overrun is the air whipped into the mix during freezing, measured by weight from the same container filled with mix and then with frozen ice cream: overrun = (mix weight − frozen weight) ÷ frozen weight × 100. A mix that drops from 1000 g to 625 g in the cup ran 60 % overrun. Dense gelato sits around 20–35 %, premium ice cream 25–50 %, soft-serve and economy tubs 50–100 %+ — more air means lighter, cheaper, and faster-melting.",
        "inputs": {
            "mix_weight_g": 1000,
            "frozen_weight_g": 625
        },
        "overrun_pct": 60,
        "air_volume_fraction_pct": 37.5
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.319Z",
        "request_id": "69952657-5983-4757-ba61-c14388c2f634"
    },
    "status": "ok",
    "message": "Overrun",
    "success": true
}
```

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

**Response:**
```json
{
    "data": {
        "note": "Total solids = everything that is not water (sugar + fat + milk-solids-not-fat + other), as a percent of the mix weight. Solids carry the body, flavour and scoopability; a typical ice cream runs 36–42 % total solids with ~10–16 % fat and ~9–12 % MSNF, gelato lower in fat but often higher in sugar. Balancing the solids and water is what keeps the texture smooth and not icy — too much water and it freezes hard and crystalline.",
        "inputs": {
            "fat_g": 100,
            "msnf_g": 90,
            "sugar_g": 200,
            "water_g": 600,
            "other_solids_g": 10
        },
        "fat_pct": 10,
        "msnf_pct": 9,
        "sugar_pct": 20,
        "water_pct": 60,
        "total_solids_g": 400,
        "total_weight_g": 1000,
        "total_solids_pct": 40
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.421Z",
        "request_id": "d9049b2a-585d-417c-8419-60754e2b9811"
    },
    "status": "ok",
    "message": "Total solids",
    "success": true
}
```

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

**Response:**
```json
{
    "data": {
        "note": "Freezing inflates the mix by its overrun, so the frozen volume = the mix volume × (1 + overrun/100) and the servings = that ÷ the scoop size, rounded down. 2 litres of mix at 60 % overrun yields 3.2 litres — about 53 sixty-millilitre scoops. This is why overrun is a cost lever: the same mix stretches to far more servings at higher overrun, at the price of body and richness.",
        "inputs": {
            "scoop_ml": 60,
            "overrun_pct": 60,
            "mix_volume_ml": 2000
        },
        "scoops": 53,
        "final_volume_l": 3.2,
        "final_volume_ml": 3200
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.514Z",
        "request_id": "1db47efa-af0a-415a-b52b-8867f013456e"
    },
    "status": "ok",
    "message": "Yield",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Grams, ml, percent. overrun = (mix−frozen)/frozen·100; final volume = mix·(1+overrun/100); total solids = (mix−water)/mix·100. Recipe-balance maths. For cooking/measure conversions use a cooking API.",
        "service": "icecream-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/yield": "Frozen volume and scoop count from mix volume and overrun.",
            "GET /v1/overrun": "Overrun percent from mix and frozen weights of the same volume.",
            "GET /v1/total-solids": "Total solids and component percentages of a mix."
        },
        "description": "Ice-cream / gelato batch maths: overrun (whipped-in air), frozen yield and scoop count, and the total-solids balance of a mix."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.619Z",
        "request_id": "a739d599-7321-4861-a24c-3e1cd7aa01c6"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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