# Construction Calculator API
> Construction and material estimating as an API — the everyday "how much do I need to buy" maths for building and renovation jobs, computed locally and deterministically from standard geometry and trade rules of thumb. The paint endpoint works out the litres and number of cans for a surface, allowing for the number of coats and the paint's coverage and deducting doors and windows. The tile endpoint computes how many tiles (and full boxes) a floor or wall area needs from the tile dimensions and a wastage allowance. The concrete endpoint gives the concrete volume in cubic metres, cubic yards and litres — and the number of pre-mix bags — for a slab, footing, wall or round column, with an optional batch quantity. The bricks endpoint computes how many bricks a wall needs from the brick size and mortar joint (default 215×65 mm brick with a 10 mm joint ≈ 60 bricks per square metre). Everything is computed locally and deterministically, so it is instant and private. Ideal for builders' merchants and trade apps, DIY and home-improvement tools, quoting and estimating software, and project planners. Pure local computation — no key, no third-party service, instant. Live, nothing stored. Estimates are guidance — allow for site conditions and follow the manufacturer's stated figures. 4 endpoints. This is materials estimating; for plain unit conversion use a unit-conversion API and for tyre or drivetrain maths use a tyre 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/buildcalc-api/..."
```

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

## Endpoints

### Build

#### `GET /v1/bricks` — Bricks needed

**Parameters:**
- `area` (query, optional, string) — wall m² (or length+height) Example: `10`
- `brick_length` (query, optional, string) — default 215 Example: `215`
- `brick_height` (query, optional, string) — default 65 Example: `65`
- `mortar_joint` (query, optional, string) — default 10 Example: `10`
- `unit` (query, optional, string) — mm|cm|in (default mm) Example: `mm`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buildcalc-api/v1/bricks?area=10&brick_length=215&brick_height=65&mortar_joint=10&unit=mm"
```

**Response:**
```json
{
    "data": {
        "note": "Single-leaf (half-brick) wall, stretcher bond. Default 215×65 mm brick with a 10 mm joint ≈ 60 bricks/m². Double the count for a one-brick wall.",
        "inputs": {
            "unit": "mm",
            "area_m2": 10,
            "brick_height": 65,
            "brick_length": 215,
            "mortar_joint": 10,
            "waste_percent": 5
        },
        "bricks_needed": 623,
        "bricks_per_m2": 59.26
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.680Z",
        "request_id": "374bf229-1811-46ec-be0d-9006f158ed02"
    },
    "status": "ok",
    "message": "Brick estimator",
    "success": true
}
```

#### `GET /v1/concrete` — Concrete volume & bags

**Parameters:**
- `shape` (query, optional, string) — slab|footing|wall|column Example: `slab`
- `length` (query, optional, string) — m Example: `5`
- `width` (query, optional, string) — m Example: `4`
- `thickness` (query, optional, string) — m (slab/wall) Example: `0.1`
- `diameter` (query, optional, string) — m (column)
- `height` (query, optional, string) — m (column)
- `bag_yield_m3` (query, optional, string) — default 0.011

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buildcalc-api/v1/concrete?shape=slab&length=5&width=4&thickness=0.1"
```

**Response:**
```json
{
    "data": {
        "note": "Bag count assumes a ~0.011 m³ yield per 20 kg pre-mix bag; adjust bag_yield_m3 for your product.",
        "inputs": {
            "shape": "slab",
            "width_m": 4,
            "length_m": 5,
            "quantity": 1,
            "thickness_m": 0.1,
            "bag_yield_m3": 0.011,
            "waste_percent": 5
        },
        "volume_m3": 2,
        "volume_yd3": 2.747,
        "bags_needed": 191,
        "volume_litres": 2100,
        "volume_with_waste_m3": 2.1
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.791Z",
        "request_id": "bbe7ac9f-4d18-469e-add8-cec473d83280"
    },
    "status": "ok",
    "message": "Concrete estimator",
    "success": true
}
```

#### `GET /v1/paint` — Paint litres & cans

**Parameters:**
- `area` (query, optional, string) — m² (or length+height) Example: `40`
- `coats` (query, optional, string) — default 2 Example: `2`
- `coverage` (query, optional, string) — m²/litre per coat (default 11) Example: `11`
- `doors` (query, optional, string) — count Example: `0`
- `windows` (query, optional, string) — count Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buildcalc-api/v1/paint?area=40&coats=2&coverage=11&doors=0&windows=0"
```

**Response:**
```json
{
    "data": {
        "note": "Doors deducted at 1.8 m² and windows at 1.5 m² each. Coverage is per coat; check the tin's stated spread rate.",
        "inputs": {
            "area": 40,
            "coats": 2,
            "doors": 0,
            "windows": 0,
            "can_size_litres": 2.5,
            "coverage_m2_per_litre": 11
        },
        "cans_needed": 3,
        "litres_needed": 7.27,
        "litres_rounded": 7.300000000000001,
        "paintable_area_m2": 40
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:00.892Z",
        "request_id": "1f5ccfc1-ef04-45be-b6f9-7e54967b14df"
    },
    "status": "ok",
    "message": "Paint estimator",
    "success": true
}
```

#### `GET /v1/tile` — Tiles & boxes needed

**Parameters:**
- `area` (query, optional, string) — m² (or length+width) Example: `12`
- `tile_width` (query, required, string) — tile width Example: `30`
- `tile_length` (query, required, string) — tile length Example: `30`
- `tile_unit` (query, optional, string) — mm|cm|m|in (default cm) Example: `cm`
- `waste_percent` (query, optional, string) — default 10 Example: `10`
- `tiles_per_box` (query, optional, string) — for box count

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buildcalc-api/v1/tile?area=12&tile_width=30&tile_length=30&tile_unit=cm&waste_percent=10"
```

**Response:**
```json
{
    "data": {
        "note": "Includes wastage allowance; round up to full boxes when ordering.",
        "inputs": {
            "area_m2": 12,
            "tile_unit": "cm",
            "tile_width": 30,
            "tile_length": 30,
            "waste_percent": 10
        },
        "tile_area_m2": 0.09,
        "tiles_needed": 147,
        "tiles_per_m2": 11.11,
        "area_with_waste_m2": 13.2
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.013Z",
        "request_id": "d54e4aaf-cdfb-4da3-88c7-6bdca19e5a4c"
    },
    "status": "ok",
    "message": "Tile estimator",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Estimates are guidance — allow for site conditions and follow the manufacturer's stated figures.",
        "service": "buildcalc",
        "endpoints": {
            "/v1/tile": "Number of tiles (and boxes) for a floor/wall area, including wastage.",
            "/v1/paint": "Litres and cans of paint for a surface area (deducts doors/windows, accounts for coats and coverage).",
            "/v1/bricks": "Number of bricks for a wall area given brick size and mortar joint.",
            "/v1/concrete": "Concrete volume (m³, yd³, litres) and pre-mix bags for a slab, footing, wall or round column."
        },
        "description": "Construction & materials estimators: paint, tiles, concrete and bricks, computed locally from standard geometry and trade rules."
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.101Z",
        "request_id": "dd4a2fa9-2f76-413d-a1c7-f74201cf427d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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