# Mulch & Material Volume API
> Landscape-material volume estimating as an API, computed locally and deterministically. The volume endpoint computes how much mulch, topsoil, compost or gravel a bed needs as area × depth — from an explicit area or from length × width or a circular diameter/radius, with the depth given in metres, centimetres, feet or inches — and reports the result in cubic metres, cubic yards, cubic feet and litres; a 10 m × 5 m bed at 7.5 cm (3 in) deep needs 3.75 m³, about 4.9 cubic yards, and pass a bag size to also get the number of bags (75 fifty-litre bags). The coverage endpoint inverts it: the area a known volume covers at a chosen depth — one cubic yard at 2 inches deep covers about 15 m² (162 sq ft). The bags endpoint returns how many bags of a given litre size supply a required volume. Lengths use unit=m (default) or unit=ft, and depth also accepts depth_cm or depth_inches. Everything is computed locally and deterministically, so it is instant and private. Ideal for landscaping, gardening, home-improvement, nursery, hardscape and contractor-estimating app developers, mulch-and-soil calculators and material-ordering tools, and trade software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is loose-material volume by geometry; for structural concrete mixes use a concrete 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/mulch-api/..."
```

## Pricing
- **Free** (Free) — 6,800 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 68,000 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 300,000 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,620,000 calls/Mo, 40 req/s

## Endpoints

### Mulch

#### `GET /v1/bags` — Bags needed for a volume

**Parameters:**
- `cubic_meters` (query, optional, string) — Required volume (m³) Example: `3.75`
- `cubic_yards` (query, optional, string) — Or cubic yards
- `bag_liters` (query, required, string) — Bag size (litres) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mulch-api/v1/bags?cubic_meters=3.75&bag_liters=50"
```

**Response:**
```json
{
    "data": {
        "note": "Bags = ⌈total litres / bag size⌉. A 50 L bag yields 0.05 m³, so 3.75 m³ needs 75 bags.",
        "inputs": {
            "volume_m3": 3.75,
            "bag_liters": 50
        },
        "exact_bags": 75,
        "bags_needed": 75,
        "total_liters": 3750
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:21.225Z",
        "request_id": "8ae5b5b9-3e5e-4eec-9b07-e03eacd3a041"
    },
    "status": "ok",
    "message": "Bags needed",
    "success": true
}
```

#### `GET /v1/coverage` — Coverage area for a volume

**Parameters:**
- `cubic_yards` (query, optional, string) — Volume (cubic yards) Example: `1`
- `cubic_meters` (query, optional, string) — Or cubic metres
- `liters` (query, optional, string) — Or litres
- `depth_inches` (query, optional, string) — Depth (inches) Example: `2`
- `depth_cm` (query, optional, string) — Or depth (cm)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mulch-api/v1/coverage?cubic_yards=1&depth_inches=2"
```

**Response:**
```json
{
    "data": {
        "note": "Coverage area = volume / depth. One cubic yard at 2 in deep covers about 15 m² (≈162 sq ft).",
        "inputs": {
            "depth_m": 0.0508,
            "volume_m3": 0.76455
        },
        "area_m2": 15.0503,
        "area_ft2": 162
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:21.333Z",
        "request_id": "97d810d4-7294-4421-949a-5ba34fc18892"
    },
    "status": "ok",
    "message": "Coverage area",
    "success": true
}
```

#### `GET /v1/volume` — Material volume for a bed

**Parameters:**
- `length` (query, optional, string) — Bed length Example: `10`
- `width` (query, optional, string) — Bed width Example: `5`
- `area` (query, optional, string) — Or area directly
- `diameter` (query, optional, string) — Or circular diameter
- `depth_cm` (query, optional, string) — Depth (cm) Example: `7.5`
- `depth_inches` (query, optional, string) — Or depth (inches)
- `unit` (query, optional, string) — Length unit: m or ft Example: `m`
- `bag_liters` (query, optional, string) — Bag size (litres) for bag count

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mulch-api/v1/volume?length=10&width=5&depth_cm=7.5&unit=m"
```

**Response:**
```json
{
    "data": {
        "note": "Material volume = area × depth. A 10 m × 5 m bed at 7.5 cm (3 in) deep needs 3.75 m³ (≈4.9 cubic yards).",
        "inputs": {
            "area_m2": 50,
            "depth_m": 0.075
        },
        "liters": 3750,
        "cubic_feet": 132.43,
        "cubic_yards": 4.90481,
        "cubic_meters": 3.75
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:21.440Z",
        "request_id": "130f6d83-9683-449d-ba8d-8458fde01fd1"
    },
    "status": "ok",
    "message": "Material volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Set unit=m (default) or unit=ft for lengths; depth may also be given as depth_cm or depth_inches. Volume is reported in m³, cubic yards, cubic feet and litres. For structural concrete mixes use a concrete API.",
        "service": "mulch-api",
        "endpoints": {
            "GET /v1/bags": "Number of bags to supply a required volume.",
            "GET /v1/meta": "This document.",
            "GET /v1/volume": "Material volume from a bed's area (or dimensions) and depth.",
            "GET /v1/coverage": "Area a given volume covers at a depth."
        },
        "description": "Landscape material volume — mulch, topsoil, compost or gravel for a bed: volume from area and depth, coverage, and bag counts."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:21.555Z",
        "request_id": "c37a8599-140b-4646-a8cc-9d3e2bb906e4"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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