{"openapi":"3.1.0","info":{"title":"Highway Vertical Curve API","version":"1.0.0","description":"Vertical (parabolic) road-curve geometry as an API, computed locally and deterministically — the K-value, profile-elevation and design-length numbers a highway engineer or surveyor lays a crest or sag curve out with. The geometry endpoint takes the incoming and outgoing grades and the length and returns the algebraic grade difference A = g2 − g1 (negative is a crest, positive a sag), the K value = length ÷ |A| (the headline number on every design chart), the high or low point offset −g1·L/A from the PVC, and — given the PVI station and elevation — the PVC and PVT coordinates and the turning-point station and elevation. The elevation endpoint evaluates the parabola at any station: elevation = PVC elevation + (g1/100)·x + (A/(200·L))·x², with the instantaneous grade g1 + (A/L)·x that sweeps smoothly from g1 to g2 — the smooth change of grade that makes the ride and sight line comfortable. The min-length endpoint gives the AASHTO minimum length for stopping sight distance: crest L = A·S² ÷ 2158 and sag (headlight) L = A·S² ÷ (400 + 3.5·S), with the controlling K, because a crest hides the road over the hump and a sag limits the headlight reach at night. Everything is computed locally and deterministically, so it is instant and private. Ideal for highway- and rail-design tools, surveying and civil-engineering utilities, and CAD/GIS profile work. Pure local computation — no key, no third-party service, instant. US units (ft, %, mph). 3 compute endpoints. For horizontal curves use a horizontal-curve API; for slope conversion a slope API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/verticalcurve-api","description":"oanor gateway"}],"tags":[{"name":"Curve"},{"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/elevation":{"get":{"operationId":"get_v1_elevation","tags":["Curve"],"summary":"Elevation and grade at a station","description":"","parameters":[{"name":"pvc_elevation_ft","in":"query","required":true,"description":"PVC elevation (ft)","schema":{"type":"string"},"example":"94"},{"name":"grade_in_pct","in":"query","required":true,"description":"Incoming grade g1 (%)","schema":{"type":"string"},"example":"3"},{"name":"grade_out_pct","in":"query","required":true,"description":"Outgoing grade g2 (%)","schema":{"type":"string"},"example":"-2"},{"name":"length_ft","in":"query","required":true,"description":"Curve length (ft)","schema":{"type":"string"},"example":"400"},{"name":"distance_from_pvc_ft","in":"query","required":true,"description":"Distance from PVC (ft)","schema":{"type":"string"},"example":"240"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Elevation on the curve = PVC elevation + (g1/100)·x + (A/(200·L))·x², the parabola, with x measured along the road from the PVC. The instantaneous grade is g1 + (A/L)·x, which sweeps smoothly from g1 to g2 — that steady change of grade is what makes the ride and the sight line comfortable. Set up the road profile by evaluating this at each station.","inputs":{"length_ft":400,"grade_in_pct":3,"grade_out_pct":-2,"pvc_elevation_ft":94,"distance_from_pvc_ft":240},"elevation_ft":97.6,"grade_at_point_pct":0},"meta":{"timestamp":"2026-06-07T08:18:02.851Z","request_id":"1ad0d206-9a3e-4916-be3a-466e6b34be18"},"status":"ok","message":"Elevation","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/geometry":{"get":{"operationId":"get_v1_geometry","tags":["Curve"],"summary":"K value, type and turning point","description":"","parameters":[{"name":"grade_in_pct","in":"query","required":true,"description":"Incoming grade g1 (%)","schema":{"type":"string"},"example":"3"},{"name":"grade_out_pct","in":"query","required":true,"description":"Outgoing grade g2 (%)","schema":{"type":"string"},"example":"-2"},{"name":"length_ft","in":"query","required":true,"description":"Curve length (ft)","schema":{"type":"string"},"example":"400"},{"name":"pvi_station_ft","in":"query","required":false,"description":"PVI station (ft) for coordinates","schema":{"type":"string"},"example":"5000"},{"name":"pvi_elevation_ft","in":"query","required":false,"description":"PVI elevation (ft) for coordinates","schema":{"type":"string"},"example":"100"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"A vertical curve is a parabola joining two grades: the algebraic difference A = g2 − g1 (negative = crest, positive = sag), and the K value = length ÷ |A| is the length per percent — the headline number on every design chart. The high or low point, where the grade passes through zero, sits at −g1·L/A from the PVC; if that falls outside the curve the summit/sag is at one end. Give the PVI station and elevation to get the PVC/PVT and turning-point coordinates.","inputs":{"length_ft":400,"grade_in_pct":3,"grade_out_pct":-2},"k_value":80,"curve_type":"crest","pvc_station_ft":4800,"pvt_station_ft":5200,"pvc_elevation_ft":94,"pvt_elevation_ft":96,"turning_point_offset_ft":240,"algebraic_grade_diff_pct":-5,"turning_point_station_ft":5040,"turning_point_elevation_ft":97.6},"meta":{"timestamp":"2026-06-07T08:18:02.947Z","request_id":"0a1c1c52-0729-491e-adbc-3b7d2b46a712"},"status":"ok","message":"Curve geometry","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/min-length":{"get":{"operationId":"get_v1_min_length","tags":["Curve"],"summary":"Minimum length for sight distance","description":"","parameters":[{"name":"grade_diff_pct","in":"query","required":true,"description":"Algebraic grade difference A (%)","schema":{"type":"string"},"example":"5"},{"name":"sight_distance_ft","in":"query","required":true,"description":"Stopping sight distance (ft)","schema":{"type":"string"},"example":"570"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Minimum curve length for stopping sight distance (AASHTO, S < L): crest L = A·S² ÷ 2158, sag (headlight) L = A·S² ÷ (400 + 3.5·S). A crest hides the road over the hump, a sag limits the headlight reach at night, so each needs enough length for the driver to see and stop. Dividing by A gives the controlling K value to round up to a design standard.","sag_k":135.66,"inputs":{"grade_diff_pct":5,"sight_distance_ft":570},"crest_k":150.56,"sag_min_length_ft":678.3,"crest_min_length_ft":752.8},"meta":{"timestamp":"2026-06-07T08:18:03.046Z","request_id":"1743f438-2160-4694-9de1-8ddf48b87194"},"status":"ok","message":"Min length","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, %, mph). A = g2−g1; K = L/|A|; elevation = PVC + (g1/100)x + (A/200L)x²; turning point at −g1·L/A from PVC; crest Lmin = A·S²/2158, sag = A·S²/(400+3.5S). For horizontal curves use a horizontal-curve API; for slope conversion a slope API.","service":"verticalcurve-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/geometry":"A, K, crest/sag, high/low point and PVC/PVT from the grades and length.","GET /v1/elevation":"Elevation and grade at a distance from the PVC.","GET /v1/min-length":"Minimum crest/sag length for a stopping sight distance."},"description":"Vertical (parabolic) road-curve geometry: K value & turning point, elevation at a station, and AASHTO minimum length for sight distance."},"meta":{"timestamp":"2026-06-07T08:18:03.128Z","request_id":"7b267a00-1428-4e8e-88f3-033c4a19df86"},"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":5000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1200,"monthly_call_quota":52000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3800,"monthly_call_quota":220000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":11750,"monthly_call_quota":1130000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/verticalcurve-api"}