# Blood Alcohol Calculator API
> Blood-alcohol estimation as an API, using the Widmark equation, computed locally and deterministically. The estimate endpoint works out the peak and current blood-alcohol concentration — in both per mille (‰) and percent (%) — from the alcohol consumed, body weight, sex and the time elapsed since drinking, and tells you roughly how long until you are sober or back under a chosen legal limit. Alcohol can be given as grams, as US standard drinks, or as a drink volume and ABV. The drink endpoint is a standard-drink calculator: from a volume and ABV it returns the grams of pure alcohol, US standard drinks (14 g), UK units (10 ml) and EU standard drinks (10 g). The sober endpoint estimates the time for a current BAC to fall to zero or to a target limit at a chosen elimination rate. Everything is computed locally and deterministically, so it is instant and private. IMPORTANT: this is a rough estimate for educational use only — real blood-alcohol depends on many personal and situational factors. Never use it to decide whether it is safe or legal to drive; when in doubt, do not drive. Ideal for educational and harm-reduction tools, hospitality and event apps, and personal drink trackers. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is blood-alcohol maths; for the calories or nutrition of drinks use a food or nutrition 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/bac-api/..."
```

## Pricing
- **Free** (Free) — 9,235 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 18,850 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 238,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,235,000 calls/Mo, 50 req/s

## Endpoints

### BAC

#### `GET /v1/drink` — Standard drink calculator

**Parameters:**
- `volume` (query, required, string) — Drink volume ml Example: `355`
- `abv` (query, required, string) — ABV % Example: `5`
- `count` (query, optional, string) — Number of drinks Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bac-api/v1/drink?volume=355&abv=5&count=1"
```

**Response:**
```json
{
    "data": {
        "input": {
            "abv": 5,
            "count": 1,
            "volume_ml": 355
        },
        "uk_units": 1.78,
        "disclaimer": "Rough estimate for education only — never use to decide whether it is safe or legal to drive. When in doubt, do not drive.",
        "alcohol_grams": 14,
        "pure_alcohol_ml": 17.75,
        "eu_standard_drinks": 1.4,
        "us_standard_drinks": 1
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.219Z",
        "request_id": "711f2ae4-fded-48ce-8d98-08c2927ae64f"
    },
    "status": "ok",
    "message": "Standard drink calculator",
    "success": true
}
```

#### `GET /v1/estimate` — Estimate blood alcohol (Widmark)

**Parameters:**
- `weight` (query, required, string) — Body weight Example: `80`
- `weight_unit` (query, optional, string) — kg|lb (default kg) Example: `kg`
- `sex` (query, required, string) — male|female Example: `male`
- `standard_drinks` (query, optional, string) — US standard drinks Example: `3`
- `alcohol_grams` (query, optional, string) — Or grams of alcohol
- `volume` (query, optional, string) — Or drink volume ml
- `abv` (query, optional, string) — With volume: ABV %
- `hours` (query, optional, string) — Hours since drinking Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bac-api/v1/estimate?weight=80&weight_unit=kg&sex=male&standard_drinks=3&hours=1"
```

**Response:**
```json
{
    "data": {
        "input": {
            "r": 0.68,
            "sex": "male",
            "hours": 1,
            "weight_kg": 80,
            "alcohol_grams": 42,
            "beta_per_mille_per_hour": 0.15
        },
        "status": "impaired (over many EU limits)",
        "disclaimer": "Rough estimate for education only — never use to decide whether it is safe or legal to drive. When in doubt, do not drive.",
        "peak_permille": 0.772,
        "current_permille": 0.622,
        "peak_bac_percent": 0.0772,
        "current_bac_percent": 0.0622,
        "legal_limit_permille": 0.5,
        "hours_until_under_limit": 0.81,
        "hours_until_sober_from_peak": 5.15
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.321Z",
        "request_id": "e2256413-f403-4fe1-b5e5-0c9ee9e1b4fe"
    },
    "status": "ok",
    "message": "Estimate blood alcohol",
    "success": true
}
```

#### `GET /v1/sober` — Time until sober / under limit

**Parameters:**
- `permille` (query, optional, string) — Current BAC in ‰ Example: `0.8`
- `bac_percent` (query, optional, string) — Or current BAC in %
- `target_permille` (query, optional, string) — Target ‰ (default 0) Example: `0`
- `beta` (query, optional, string) — Elimination ‰/h (default 0.15) Example: `0.15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bac-api/v1/sober?permille=0.8&target_permille=0&beta=0.15"
```

**Response:**
```json
{
    "data": {
        "input": {
            "permille": 0.8,
            "bac_percent": 0.08,
            "target_permille": 0,
            "beta_per_mille_per_hour": 0.15
        },
        "status": "over most legal limits — clearly impaired",
        "disclaimer": "Rough estimate for education only — never use to decide whether it is safe or legal to drive. When in doubt, do not drive.",
        "hours_until_target": 5.33,
        "minutes_until_target": 320
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.439Z",
        "request_id": "55b623c9-7709-4f52-9f61-8f38dde89630"
    },
    "status": "ok",
    "message": "Time to sober",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Per mille (‰) = g alcohol / (r · kg). BAC % ≈ ‰ ÷ 10.",
        "service": "bac",
        "constants": {
            "widmark_r_male": 0.68,
            "widmark_r_female": 0.55,
            "ethanol_density_g_per_ml": 0.789,
            "default_elimination_permille_per_hour": 0.15
        },
        "endpoints": {
            "/v1/drink": "Standard-drink calculator: alcohol grams, US standard drinks, UK units and EU drinks from volume + ABV.",
            "/v1/sober": "Time until BAC falls to zero or a target limit from a current value.",
            "/v1/estimate": "Estimate peak and current BAC (‰ and %) from drinks, body weight, sex and time elapsed."
        },
        "disclaimer": "Rough estimate for education only — never use to decide whether it is safe or legal to drive. When in doubt, do not drive.",
        "description": "Blood-alcohol estimation via the Widmark equation, with standard-drink and time-to-sober helpers."
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.548Z",
        "request_id": "a5fcd281-0fd0-4903-9614-b7e1327c8a30"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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