{"openapi":"3.1.0","info":{"title":"Earthwork Volume API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/earthwork-api","description":"oanor gateway"}],"tags":[{"name":"Earthwork"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/average-end-area":{"get":{"operationId":"get_v1_average_end_area","tags":["Earthwork"],"summary":"Volume between two cross-sections","description":"","parameters":[{"name":"area1_sqft","in":"query","required":true,"description":"End area 1 (ft²)","schema":{"type":"string"},"example":"100"},{"name":"area2_sqft","in":"query","required":true,"description":"End area 2 (ft²)","schema":{"type":"string"},"example":"150"},{"name":"distance_ft","in":"query","required":true,"description":"Distance between sections (ft)","schema":{"type":"string"},"example":"100"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/prismoidal":{"get":{"operationId":"get_v1_prismoidal","tags":["Earthwork"],"summary":"Prismoidal (Simpson) volume","description":"","parameters":[{"name":"area1_sqft","in":"query","required":true,"description":"End area 1 (ft²)","schema":{"type":"string"},"example":"100"},{"name":"area_mid_sqft","in":"query","required":true,"description":"Middle area (ft²)","schema":{"type":"string"},"example":"125"},{"name":"area2_sqft","in":"query","required":true,"description":"End area 2 (ft²)","schema":{"type":"string"},"example":"150"},{"name":"length_ft","in":"query","required":true,"description":"Total length (ft)","schema":{"type":"string"},"example":"100"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/soil-state":{"get":{"operationId":"get_v1_soil_state","tags":["Earthwork"],"summary":"Bank ↔ loose ↔ compacted","description":"","parameters":[{"name":"bank_cubic_yards","in":"query","required":true,"description":"Bank (in-situ) volume (cy)","schema":{"type":"string"},"example":"1000"},{"name":"swell_pct","in":"query","required":false,"description":"Swell % (default 25)","schema":{"type":"string"},"example":"25"},{"name":"shrinkage_pct","in":"query","required":false,"description":"Shrinkage % (default 10)","schema":{"type":"string"},"example":"10"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":5100,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1210,"monthly_call_quota":52500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3810,"monthly_call_quota":222000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":11820,"monthly_call_quota":1135000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/earthwork-api"}