# Paint Calculator API
> Paint estimating and mixing maths as an API, computed locally and deterministically. The coverage endpoint works out how much paint an area needs — paint = area × coats ÷ spreading rate — from an area (in square metres or square feet), the number of coats and the paint's coverage (in m² per litre or square feet per US gallon, defaulting to a typical emulsion), and returns the volume in litres and US gallons and, given a tin size, the number of tins to buy. The room endpoint computes the paintable wall area of a room from its length, width and height — perimeter × height minus the door and window openings, optionally plus the ceiling — and then the paint needed, with sensible default door and window sizes you can override. The ratio endpoint splits a total volume by a mixing ratio such as 4:1 (base to hardener) or 4:1:10 (base, hardener, thinner) into each component's amount and percentage, or scales the whole mix up from one known component amount — for two-part epoxies, catalysed paints and thinning. Everything is computed locally and deterministically, so it is instant and private. Ideal for decorating, trade and DIY tools, hardware-store and paint-shop apps, estimating and quoting software, and home-improvement projects. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is paint coverage and mixing; for mulch, soil and gravel volumes use a landscaping 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/paint-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($11/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($39/Mo) — 1,530,000 calls/Mo, 40 req/s

## Endpoints

### Paint

#### `GET /v1/coverage` — Paint needed for an area

**Parameters:**
- `area` (query, optional, string) — Area (m²) Example: `50`
- `area_sqft` (query, optional, string) — Or area (sq ft)
- `coats` (query, optional, string) — Number of coats (default 2) Example: `2`
- `coverage` (query, optional, string) — Coverage (m²/L, default 11)
- `can_size` (query, optional, string) — Tin size (L) for tin count Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paint-api/v1/coverage?area=50&coats=2&can_size=5"
```

**Response:**
```json
{
    "data": {
        "coats": 2,
        "area_m2": 50,
        "formula": "paint = area · coats / coverage_rate.",
        "cans_needed": 2,
        "paint_litres": 9.0909,
        "can_size_litres": 5,
        "paint_us_gallons": 2.4016,
        "coverage_m2_per_litre": 11
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:51.623Z",
        "request_id": "a38276a1-1e53-4507-9c83-08e4f8b654df"
    },
    "status": "ok",
    "message": "Paint needed for an area",
    "success": true
}
```

#### `GET /v1/ratio` — Split a volume by a mixing ratio

**Parameters:**
- `ratio` (query, required, string) — Mixing ratio, e.g. 4:1 or 4:1:10 Example: `4:1`
- `total` (query, optional, string) — Total volume to split Example: `5`
- `known_part_amount` (query, optional, string) — Or scale from one known component
- `known_part_index` (query, optional, string) — Index of the known component (0-based)
- `labels` (query, optional, string) — Optional component labels (comma-separated) Example: `base,hardener`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paint-api/v1/ratio?ratio=4%3A1&total=5&labels=base%2Chardener"
```

**Response:**
```json
{
    "data": {
        "ratio": "4:1",
        "formula": "each component = total · part / sum(parts).",
        "ratio_sum": 5,
        "components": [
            {
                "index": 0,
                "label": "base",
                "ratio": 4,
                "amount": 4,
                "percent": 80
            },
            {
                "index": 1,
                "label": "hardener",
                "ratio": 1,
                "amount": 1,
                "percent": 20
            }
        ],
        "total_volume": 5
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:51.761Z",
        "request_id": "e970a496-bc21-469b-b587-36fd7aba509a"
    },
    "status": "ok",
    "message": "Split a volume by a mixing ratio",
    "success": true
}
```

#### `GET /v1/room` — Paintable wall area of a room

**Parameters:**
- `length` (query, required, string) — Room length (m) Example: `4`
- `width` (query, required, string) — Room width (m) Example: `3`
- `height` (query, required, string) — Room height (m) Example: `2.5`
- `doors` (query, optional, string) — Number of doors (default 1) Example: `1`
- `windows` (query, optional, string) — Number of windows (default 0) Example: `2`
- `include_ceiling` (query, optional, string) — Include the ceiling (true/false) Example: `false`
- `coats` (query, optional, string) — Number of coats (default 2) Example: `2`
- `coverage` (query, optional, string) — Coverage (m²/L, default 11)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paint-api/v1/room?length=4&width=3&height=2.5&doors=1&windows=2&include_ceiling=false&coats=2"
```

**Response:**
```json
{
    "data": {
        "coats": 2,
        "doors": 1,
        "formula": "paintable = perimeter · height − doors − windows (+ ceiling); paint = paintable · coats / coverage.",
        "width_m": 3,
        "windows": 2,
        "height_m": 2.5,
        "length_m": 4,
        "perimeter_m": 14,
        "paint_litres": 5.5273,
        "ceiling_area_m2": 0,
        "include_ceiling": false,
        "openings_area_m2": 4.6,
        "paint_us_gallons": 1.4602,
        "paintable_area_m2": 30.4,
        "gross_wall_area_m2": 35,
        "coverage_m2_per_litre": 11
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:51.868Z",
        "request_id": "d7834b9c-9b4c-4680-a8ef-99f7037b839c"
    },
    "status": "ok",
    "message": "Paintable wall area of a room",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "paint",
        "note": "Paint estimating & mixing maths — computed locally and deterministically, no key, no third-party service.",
        "defaults": {
            "coats": 2,
            "door_area_m2": 1.8,
            "window_area_m2": 1.4,
            "coverage_m2_per_litre": 11
        },
        "endpoints": [
            "/v1/coverage",
            "/v1/room",
            "/v1/ratio",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:51.979Z",
        "request_id": "d6ac120f-bf51-4695-95ac-834419395e81"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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