{"openapi":"3.1.0","info":{"title":"Ship Stability API","version":"1.0.0","description":"Ship initial-stability maths as an API, computed locally and deterministically — the metacentric-height, righting-moment and rolling-period numbers a naval architect, ship officer or marine-surveyor judges a vessel by. The metacentric-height endpoint gives GM = KM − KG, the single most important stability figure: the height of the metacentre (set by the hull form and draught) above the centre of gravity (set by how the ship is loaded), with a classification from a dangerous negative GM, through tender and comfortable, to a stiff GM that rolls violently — naval architects aim for the middle, because too little is unsafe and too much is hard on cargo and crew. The righting-moment endpoint gives the small-angle righting arm GZ ≈ GM · sin(heel) and the righting moment (GZ × displacement) that pushes the ship back upright, valid up to roughly 7–10° before the true GZ curve bends away. The roll-period endpoint gives the natural transverse rolling period T = 2π·k / √(g·GM) from the GM and beam — the same relation sailors run in reverse as the rolling-period test, where a suddenly longer roll warns that GM has dropped. Everything is computed locally and deterministically, so it is instant and private. Ideal for naval-architecture and ship-design tools, marine-surveyor and loading-software utilities, maritime-training apps and stability dashboards. Pure local computation — no key, no third-party service, instant. Initial-stability estimates — use full KN cross-curves for large angles. 3 compute endpoints. For hull speed and design ratios use a sailing API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/shipstability-api","description":"oanor gateway"}],"tags":[{"name":"Stability"},{"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/metacentric-height":{"get":{"operationId":"get_v1_metacentric_height","tags":["Stability"],"summary":"Metacentric height GM","description":"","parameters":[{"name":"km_m","in":"query","required":true,"description":"Height of the metacentre above keel KM (m)","schema":{"type":"string"},"example":"8"},{"name":"kg_m","in":"query","required":true,"description":"Height of the centre of gravity above keel KG (m)","schema":{"type":"string"},"example":"7"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"gm_m":1,"note":"The metacentric height GM = KM − KG is the single most important initial-stability number: the height of the metacentre (set by the hull form and draught) above the centre of gravity (set by loading). Positive GM means the ship returns upright; negative GM means it lolls or capsizes. Too small is dangerous, but too large gives a violent, cargo-damaging roll — naval architects aim for a comfortable middle.","inputs":{"kg_m":7,"km_m":8},"stability":"very stiff — violent roll, hard on cargo and crew"},"meta":{"timestamp":"2026-06-06T23:53:53.940Z","request_id":"824989c6-77b0-466d-8c5e-4a097f8fe15b"},"status":"ok","message":"Metacentric height","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/righting-moment":{"get":{"operationId":"get_v1_righting_moment","tags":["Stability"],"summary":"Righting arm GZ and righting moment","description":"","parameters":[{"name":"gm_m","in":"query","required":true,"description":"Metacentric height GM (m)","schema":{"type":"string"},"example":"1.0"},{"name":"heel_deg","in":"query","required":true,"description":"Heel angle (degrees)","schema":{"type":"string"},"example":"10"},{"name":"displacement_t","in":"query","required":true,"description":"Displacement (tonnes)","schema":{"type":"string"},"example":"5000"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"For small heel angles the righting arm GZ ≈ GM · sin(heel), and the righting moment that pushes the ship back upright = GZ × displacement. This linear relation holds up to roughly 7–10°; beyond that the true GZ curve bends away from it as the deck edge nears the water, so use a full cross-curve (KN) analysis for large angles. A bigger GM gives a steeper initial righting arm.","inputs":{"gm_m":1,"heel_deg":10,"displacement_t":5000},"righting_arm_gz_m":0.1736,"righting_moment_t_m":868.2,"righting_moment_kn_m":8514.5},"meta":{"timestamp":"2026-06-06T23:53:54.026Z","request_id":"4202dbb9-2713-4fb6-8d7f-cef349e613dc"},"status":"ok","message":"Righting moment","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/roll-period":{"get":{"operationId":"get_v1_roll_period","tags":["Stability"],"summary":"Natural rolling period","description":"","parameters":[{"name":"gm_m","in":"query","required":true,"description":"Metacentric height GM (m)","schema":{"type":"string"},"example":"1.0"},{"name":"beam_m","in":"query","required":true,"description":"Beam / breadth (m)","schema":{"type":"string"},"example":"15"},{"name":"roll_gyration_factor","in":"query","required":false,"description":"Gyration factor k=c·B (default 0.35)","schema":{"type":"string"},"example":"0.35"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The natural rolling period T = 2π·k / √(g·GM), where k is the transverse radius of gyration (about 0.34–0.40 of the beam for a typical ship). A stiff ship (large GM) rolls fast with a short period; a tender ship rolls slowly. Sailors run this in reverse as the 'rolling-period test' — timing the roll to estimate GM — and a period that suddenly lengthens warns that GM has dropped dangerously.","inputs":{"gm_m":1,"beam_m":15,"roll_gyration_factor":0.35},"roll_period_s":10.53,"radius_of_gyration_m":5.25},"meta":{"timestamp":"2026-06-06T23:53:54.115Z","request_id":"9c63a356-cfc1-46de-81d3-1a7a316396da"},"status":"ok","message":"Roll period","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":"Metric (m, t, °, s). GM = KM − KG; GZ ≈ GM·sin(heel) (small angles ≤ ~10°); T = 2π·k/√(g·GM), k ≈ 0.35·beam. Initial-stability estimates — use full KN cross-curves for large angles. For hull speed and design ratios use a sailing API.","service":"shipstability-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/roll-period":"Natural transverse rolling period from GM and beam.","GET /v1/righting-moment":"Small-angle righting arm GZ and righting moment.","GET /v1/metacentric-height":"GM = KM − KG with a stability classification."},"description":"Ship initial-stability maths: metacentric height GM, the righting arm and moment at a heel angle, and the natural rolling period."},"meta":{"timestamp":"2026-06-06T23:53:54.201Z","request_id":"f583980d-93ae-46fa-9d20-fdea7c230244"},"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":4500,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1380,"monthly_call_quota":49000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":4150,"monthly_call_quota":213000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":12900,"monthly_call_quota":1130000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/shipstability-api"}