# Candy Temperature API
> Candy-making maths as an API, computed locally and deterministically — the sugar-syrup stage numbers a confectioner reads a thermometer by. As sugar syrup boils it passes through named stages, each a temperature window with its own texture and uses, and getting within a few degrees is the difference between fudge and toffee. The stage endpoint names the stage for a temperature: 238 °F is the soft-ball stage (fudge, fondant, pralines), 305 °F is hard-crack (toffee, brittle, lollipops), and it handles °F or °C and the off-the-chart cases — still a thin syrup below thread, or darkening to burnt past caramel. The range endpoint gives the temperature window and uses of a named stage, from thread (223–234 °F) through soft-ball, firm-ball, hard-ball, soft-crack and hard-crack to caramel (320–350 °F), in both °F and °C. The altitude endpoint applies the rule that matters in the mountains: cook to 1 °F lower for every 500 feet of elevation, since water boils cooler, so a 300 °F hard-crack recipe is done at 290 °F at 5,000 feet. Everything is computed locally and deterministically, so it is instant and private. Ideal for baking, confectionery, recipe and kitchen app developers, candy-thermometer and timer tools, and cooking-class software. Pure local computation — no key, no third-party service, instant. Use a calibrated thermometer. 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/candytemp-api/..."
```

## Pricing
- **Free** (Free) — 7,080 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 57,100 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 238,800 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,364,000 calls/Mo, 40 req/s

## Endpoints

### Candy

#### `GET /v1/altitude` — Altitude-adjusted target

**Parameters:**
- `sea_level_temp` (query, required, string) — Sea-level target temperature Example: `300`
- `altitude` (query, required, string) — Altitude Example: `5000`
- `unit` (query, optional, string) — temp unit f or c (default f) Example: `f`
- `altitude_unit` (query, optional, string) — ft or m (default ft) Example: `ft`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/candytemp-api/v1/altitude?sea_level_temp=300&altitude=5000&unit=f&altitude_unit=ft"
```

**Response:**
```json
{
    "data": {
        "note": "Cook candy to 1 °F lower for every 500 ft of elevation (water boils cooler, so sugar concentrates at a lower reading). At 5,000 ft a 300 °F hard-crack recipe is done at 290 °F. Or test the syrup in cold water instead of trusting the thermometer alone.",
        "inputs": {
            "unit": "f",
            "altitude_ft": 5000,
            "sea_level_temp": 300
        },
        "adjustment_f": -10,
        "adjusted_temp_c": 143.3,
        "adjusted_temp_f": 290
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.743Z",
        "request_id": "667a2ed0-2599-4e39-9caf-d71e127e06fe"
    },
    "status": "ok",
    "message": "Altitude adjust",
    "success": true
}
```

#### `GET /v1/range` — Temperature range of a stage

**Parameters:**
- `stage` (query, required, string) — thread, soft-ball, firm-ball, hard-ball, soft-crack, hard-crack, caramel Example: `hard-ball`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/candytemp-api/v1/range?stage=hard-ball"
```

**Response:**
```json
{
    "data": {
        "note": "The hard-ball stage is 250–266 °F (121–130 °C). Use a calibrated candy thermometer; even a few degrees changes the texture.",
        "max_c": 130,
        "max_f": 266,
        "min_c": 121.1,
        "min_f": 250,
        "inputs": {
            "stage": "hard-ball"
        },
        "used_for": "nougat, marshmallows, divinity, gummies"
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.843Z",
        "request_id": "687aa1f0-b7f7-4182-aa6b-6d7815ddbbfe"
    },
    "status": "ok",
    "message": "Stage range",
    "success": true
}
```

#### `GET /v1/stage` — Stage for a temperature

**Parameters:**
- `temperature` (query, required, string) — Syrup temperature Example: `238`
- `unit` (query, optional, string) — f or c (default f) Example: `f`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/candytemp-api/v1/stage?temperature=238&unit=f"
```

**Response:**
```json
{
    "data": {
        "note": "238 °F is the soft-ball stage (235–240 °F) — for fudge, fondant, pralines, buttercreams. The classic cold-water test: a drop of syrup forms a soft ball you can feel.",
        "stage": "soft-ball",
        "inputs": {
            "unit": "f",
            "temperature": 238
        },
        "temperature_c": 114.4,
        "temperature_f": 238
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.937Z",
        "request_id": "b46c9447-9163-41ff-8d0b-279dd071ceda"
    },
    "status": "ok",
    "message": "Candy stage",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Stages °F: thread 223–234, soft-ball 235–240, firm-ball 242–248, hard-ball 250–266, soft-crack 270–290, hard-crack 300–310, caramel 320–350. Subtract 1 °F per 500 ft of altitude. Use a calibrated thermometer.",
        "service": "candytemp-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/range": "The temperature range and uses of a named stage.",
            "GET /v1/stage": "The candy stage (thread … caramel) for a temperature.",
            "GET /v1/altitude": "Altitude-adjusted target temperature (−1 °F per 500 ft)."
        },
        "description": "Candy-making maths: the sugar-syrup stage for a temperature, a stage's temperature range, and the altitude adjustment."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:53.026Z",
        "request_id": "3fb8c590-d31a-473f-ba6b-49b6c1c32eac"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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