{"openapi":"3.1.0","info":{"title":"Sonar & Underwater Sound API","version":"1.0.0","description":"Underwater-sound and sonar maths as an API, computed locally and deterministically — the speed, absorption and ranging numbers a marine engineer, sonar developer or oceanographer works with. The sound-speed endpoint gives the speed of sound in seawater from the Mackenzie nine-term equation: about 1,500 m/s — far faster than in air — rising with temperature, salinity and depth, so a profile of 25 °C, 35 ppt at 1,000 m gives 1,550.7 m/s. Because the speed varies with depth, sound rays bend and form the SOFAR channel that carries whale song and signals across whole oceans. The absorption endpoint gives Thorp's sound-absorption coefficient in dB per km against frequency, with the loss over a path: seawater swallows high frequencies fast, which is why long-range sonar and whale calls are low-pitched while high-frequency sonar gives sharp images only at short range. The echo-range endpoint turns an echo sounder's or sonar's two-way travel time into the range or depth — distance = sound speed × time ÷ 2 — so a one-second round trip at 1,500 m/s is a target 750 m away, its accuracy resting on the assumed sound speed. Everything is computed locally and deterministically, so it is instant and private. Ideal for sonar and hydrophone tools, marine-survey and bathymetry apps, ocean-acoustics research, and AUV/ROV navigation utilities. Pure local computation — no key, no third-party service, instant. Standard-equation estimates over their valid ranges. 3 compute endpoints. For the speed of sound in air and Mach use a Mach-number API; for decibels a sound-level API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/sonar-api","description":"oanor gateway"}],"tags":[{"name":"Sonar"},{"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/absorption":{"get":{"operationId":"get_v1_absorption","tags":["Sonar"],"summary":"Sound absorption vs frequency","description":"","parameters":[{"name":"frequency_khz","in":"query","required":true,"description":"Frequency (kHz)","schema":{"type":"string"},"example":"10"},{"name":"range_km","in":"query","required":false,"description":"Path length for total loss (km)","schema":{"type":"string"},"example":"5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Seawater absorbs sound more strongly at higher frequencies (Thorp's formula): low frequencies travel far, which is why long-range sonar and whale calls are low-pitched, while high-frequency sonar gives sharp images but only at short range. The loss adds to the spreading loss, so doubling the frequency roughly quadruples the absorption at sonar frequencies. Near-surface, ~4 °C water.","inputs":{"range_km":5,"frequency_khz":10},"absorption_loss_db":5.94,"absorption_db_per_km":1.187},"meta":{"timestamp":"2026-06-06T23:53:52.010Z","request_id":"7cccc13d-7ad1-46c2-bdb0-6b45f989fd6e"},"status":"ok","message":"Absorption","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/echo-range":{"get":{"operationId":"get_v1_echo_range","tags":["Sonar"],"summary":"Range/depth from echo travel time","description":"","parameters":[{"name":"travel_time_s","in":"query","required":true,"description":"Two-way travel time (s)","schema":{"type":"string"},"example":"1"},{"name":"sound_speed_m_s","in":"query","required":false,"description":"Sound speed (m/s, default 1500)","schema":{"type":"string"},"example":"1500"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"An echo sounder or sonar measures the two-way travel time, so the distance to the bottom or target = sound speed × time ÷ 2 (the sound goes out and comes back). At a typical 1,500 m/s, a one-second round trip is 750 m away. The accuracy rests on the assumed sound speed, which is why survey-grade echo sounders measure the real sound-speed profile (see /v1/sound-speed) rather than assume it.","inputs":{"travel_time_s":1,"sound_speed_m_s":1500},"range_m":750,"range_km":0.75},"meta":{"timestamp":"2026-06-06T23:53:52.091Z","request_id":"47a3d0ab-af18-4245-b593-55c545162508"},"status":"ok","message":"Echo range","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/sound-speed":{"get":{"operationId":"get_v1_sound_speed","tags":["Sonar"],"summary":"Speed of sound in seawater","description":"","parameters":[{"name":"temp_c","in":"query","required":true,"description":"Water temperature (°C)","schema":{"type":"string"},"example":"25"},{"name":"salinity_ppt","in":"query","required":false,"description":"Salinity (ppt, default 35)","schema":{"type":"string"},"example":"35"},{"name":"depth_m","in":"query","required":false,"description":"Depth (m, default 0)","schema":{"type":"string"},"example":"1000"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The speed of sound in seawater from the Mackenzie equation — about 1,500 m/s, far faster than in air, and it rises with temperature, salinity and depth (pressure). Because those vary with depth the speed forms a profile that bends sound rays, creating the SOFAR channel that carries whale song and submarine signals for thousands of kilometres. Valid roughly 2–30 °C, 25–40 ppt and to 8,000 m.","inputs":{"temp_c":25,"depth_m":1000,"salinity_ppt":35},"sound_speed_m_s":1550.74},"meta":{"timestamp":"2026-06-06T23:53:52.176Z","request_id":"083e2663-493c-47a0-a067-b929433bc7ff"},"status":"ok","message":"Sound speed","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 (°C, ppt, m, kHz, dB, m/s, s). Mackenzie nine-term sound speed; Thorp absorption; range = c·t/2. For the speed of sound in air / Mach use a Mach-number API; for decibels a sound-level API.","service":"sonar-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/absorption":"Sound absorption (dB/km) vs frequency, with optional path loss.","GET /v1/echo-range":"Range or depth from an echo's two-way travel time.","GET /v1/sound-speed":"Speed of sound in seawater from temperature, salinity and depth."},"description":"Underwater-sound / sonar maths: speed of sound in seawater (Mackenzie), Thorp absorption vs frequency, and echo range from two-way travel time."},"meta":{"timestamp":"2026-06-06T23:53:52.270Z","request_id":"06fb03c9-e7e5-4b4f-a320-7121c04ed68d"},"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":4300,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1310,"monthly_call_quota":46000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":4020,"monthly_call_quota":208000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":12600,"monthly_call_quota":1100000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/sonar-api"}