# Earthwork Volume API
> Earthwork volume maths as an API, computed locally and deterministically — the cut/fill-quantity and soil-state numbers a civil engineer, estimator or grading contractor runs for a road, trench or site. The average-end-area endpoint gives the volume between two cross-sections = the mean of the two end areas × the distance between them, ÷ 27 for cubic yards — the everyday earthwork-quantity method you sum section by section down an alignment (a 100 ft²/150 ft² pair 100 ft apart is about 463 cy). The prismoidal endpoint gives the more accurate Simpson volume = length ÷ 6 × (A₁ + 4·A_mid + A₂) using the true middle-section area, preferred for payment quantities where the average-end-area over-estimate would matter. The soil-state endpoint converts between the three states earth passes through: loose = bank × (1 + swell %) (excavating loosens it, ~25 %, so you haul more cubic yards than you cut) and compacted = bank × (1 − shrinkage %) (placing and compacting shrinks it, ~10 %) — which is why a balanced cut-and-fill needs more bank cut than the compacted fill, with the load factor for truck sizing. Everything is computed locally and deterministically, so it is instant and private. Ideal for grading and site-work estimating, surveying and civil-design tools, and earthmoving calculators. Pure local computation — no key, no third-party service, instant. US units (ft², ft, cy). 3 compute endpoints. For tank/storage volumes use a tank API; for concrete mix 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/earthwork-api/..."
```

## Pricing
- **Free** (Free) — 5,100 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 52,500 calls/Mo, 6 req/s
- **Pro** ($38/Mo) — 222,000 calls/Mo, 15 req/s
- **Mega** ($118/Mo) — 1,135,000 calls/Mo, 40 req/s

## Endpoints

### Earthwork

#### `GET /v1/average-end-area` — Volume between two cross-sections

**Parameters:**
- `area1_sqft` (query, required, string) — End area 1 (ft²) Example: `100`
- `area2_sqft` (query, required, string) — End area 2 (ft²) Example: `150`
- `distance_ft` (query, required, string) — Distance between sections (ft) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earthwork-api/v1/average-end-area?area1_sqft=100&area2_sqft=150&distance_ft=100"
```

**Response:**
```json
{
    "data": {
        "note": "The average-end-area method: volume = the mean of the two end cross-section areas × the distance between them, ÷ 27 for cubic yards. It is the everyday earthwork-quantity method along a road or trench — sum it section by section down the alignment. It slightly over-estimates when the sections differ a lot (it assumes a linear change), which the prismoidal method corrects.",
        "inputs": {
            "area1_sqft": 100,
            "area2_sqft": 150,
            "distance_ft": 100
        },
        "volume_cubic_ft": 12500,
        "volume_cubic_yards": 462.96
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:02.453Z",
        "request_id": "5f32590f-9c04-49ee-9fca-a9eaab6670c8"
    },
    "status": "ok",
    "message": "Average end area",
    "success": true
}
```

#### `GET /v1/prismoidal` — Prismoidal (Simpson) volume

**Parameters:**
- `area1_sqft` (query, required, string) — End area 1 (ft²) Example: `100`
- `area_mid_sqft` (query, required, string) — Middle area (ft²) Example: `125`
- `area2_sqft` (query, required, string) — End area 2 (ft²) Example: `150`
- `length_ft` (query, required, string) — Total length (ft) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earthwork-api/v1/prismoidal?area1_sqft=100&area_mid_sqft=125&area2_sqft=150&length_ft=100"
```

**Response:**
```json
{
    "data": {
        "note": "The prismoidal (Simpson) method: volume = length ÷ 6 × (A₁ + 4·A_mid + A₂), using the true middle-section area, ÷ 27 for cubic yards. It is more accurate than average-end-area when the cross-section changes shape along the run — the difference is the 'prismoidal correction' — and is preferred for payment quantities on big jobs where the over-estimate would matter.",
        "inputs": {
            "length_ft": 100,
            "area1_sqft": 100,
            "area2_sqft": 150,
            "area_mid_sqft": 125
        },
        "volume_cubic_ft": 12500,
        "volume_cubic_yards": 462.96
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:02.554Z",
        "request_id": "c67f2182-da1d-444b-8fb0-2027676a8137"
    },
    "status": "ok",
    "message": "Prismoidal",
    "success": true
}
```

#### `GET /v1/soil-state` — Bank ↔ loose ↔ compacted

**Parameters:**
- `bank_cubic_yards` (query, required, string) — Bank (in-situ) volume (cy) Example: `1000`
- `swell_pct` (query, optional, string) — Swell % (default 25) Example: `25`
- `shrinkage_pct` (query, optional, string) — Shrinkage % (default 10) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earthwork-api/v1/soil-state?bank_cubic_yards=1000&swell_pct=25&shrinkage_pct=10"
```

**Response:**
```json
{
    "data": {
        "note": "Soil changes volume as it is handled: excavating bank (in-situ) material loosens it — loose = bank × (1 + swell %), ~25 % for common soil — so you haul more cubic yards than you cut; placing and compacting it shrinks it below bank — compacted = bank × (1 − shrinkage %), ~10 %. So a balanced cut-and-fill needs MORE bank cut than the compacted fill volume; size trucks on loose and earthwork balance on compacted.",
        "inputs": {
            "swell_pct": 25,
            "shrinkage_pct": 10,
            "bank_cubic_yards": 1000
        },
        "load_factor": 0.8,
        "shrinkage_factor": 0.9,
        "loose_cubic_yards": 1250,
        "compacted_cubic_yards": 900
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:02.633Z",
        "request_id": "7ca8648c-91f0-40ee-bdcd-9fd1d6825563"
    },
    "status": "ok",
    "message": "Soil state",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (ft², ft, cy). AEA volume = (A₁+A₂)/2·L; prismoidal = L/6·(A₁+4A_mid+A₂); loose = bank·(1+swell), compacted = bank·(1−shrinkage); ÷27 for cubic yards. For tank/storage volumes use a tank API; for concrete mix a concrete API.",
        "service": "earthwork-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/prismoidal": "Volume by the prismoidal (Simpson) method.",
            "GET /v1/soil-state": "Bank ↔ loose ↔ compacted volume conversions.",
            "GET /v1/average-end-area": "Volume between two cross-sections (average-end-area)."
        },
        "description": "Earthwork volume maths: average-end-area and prismoidal cut/fill volumes, and bank/loose/compacted soil-state conversions."
    },
    "meta": {
        "timestamp": "2026-06-07T08:18:02.718Z",
        "request_id": "370fcd98-a81b-436d-a4a6-2be47e1eb78a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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