{"openapi":"3.1.0","info":{"title":"Hot Air Balloon Lift API","version":"1.0.0","description":"Hot-air-balloon lift maths as an API, computed locally and deterministically — the thermal-lift, envelope-temperature and air-density numbers a balloon pilot, designer or physics teacher works a flight out with. The lift endpoint gives the buoyant lift from heating the air: gross lift = envelope volume × (outside air density − inside air density), the densities from the ideal-gas law — a 2,500 m³ envelope at 100 °C on a 15 °C day lifts about 698 kg gross, from which you subtract the envelope, basket, burner and fuel for the payload, and the hotter the air and colder the day the more it lifts. The required-temp endpoint inverts it: to carry a target lift the inside air must reach a particular density and so a particular temperature, with a check that it stays under the ~120 °C that nylon envelopes can take — the everyday pre-flight question of whether the balloon can lift today's crew and fuel. The air-density endpoint gives the moist-air density ρ = (P − 0.378·Pv) ÷ (R·T), and explains the counter-intuitive fact that humid air is LESS dense than dry air, slightly cutting the lift. Everything is computed locally and deterministically, so it is instant and private. Ideal for ballooning and aviation tools, STEM and physics-education apps, and buoyancy calculators. Pure local computation — no key, no third-party service, instant. Idealised dry-lift model. 3 compute endpoints. For Archimedes flotation in water use a buoyancy API; for party-balloon helium lift a balloon API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/hotairballoon-api","description":"oanor gateway"}],"tags":[{"name":"Balloon"},{"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/air-density":{"get":{"operationId":"get_v1_air_density","tags":["Balloon"],"summary":"Moist-air density","description":"","parameters":[{"name":"temp_c","in":"query","required":true,"description":"Temperature (°C)","schema":{"type":"string"},"example":"15"},{"name":"pressure_pa","in":"query","required":false,"description":"Pressure (Pa, default 101325)","schema":{"type":"string"},"example":"101325"},{"name":"relative_humidity_pct","in":"query","required":false,"description":"Relative humidity % (default 0)","schema":{"type":"string"},"example":"50"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Air density ρ = (P − 0.378·Pv) ÷ (R·T), where Pv is the water-vapour pressure (relative humidity × the saturation pressure). Counter-intuitively, humid air is LESS dense than dry air at the same temperature and pressure, because a water molecule is lighter than the N₂/O₂ it replaces — so it slightly reduces a balloon's lift and an aircraft's performance. It falls with temperature and rises with pressure.","inputs":{"temp_c":15,"pressure_pa":101325,"relative_humidity_pct":50},"air_density_kg_m3":1.2211,"dry_air_density_kg_m3":1.225},"meta":{"timestamp":"2026-06-07T08:18:01.266Z","request_id":"254bad0f-b3a7-43a1-a24e-e2d5bbb83ec3"},"status":"ok","message":"Air density","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/lift":{"get":{"operationId":"get_v1_lift","tags":["Balloon"],"summary":"Thermal lift from the temperature difference","description":"","parameters":[{"name":"volume_m3","in":"query","required":true,"description":"Envelope volume (m³)","schema":{"type":"string"},"example":"2500"},{"name":"ambient_temp_c","in":"query","required":true,"description":"Outside air temperature (°C)","schema":{"type":"string"},"example":"15"},{"name":"internal_temp_c","in":"query","required":true,"description":"Envelope air temperature (°C)","schema":{"type":"string"},"example":"100"},{"name":"pressure_pa","in":"query","required":false,"description":"Air pressure (Pa, default 101325)","schema":{"type":"string"},"example":"101325"},{"name":"envelope_mass_kg","in":"query","required":false,"description":"Envelope + basket mass (kg) for payload","schema":{"type":"string"},"example":"250"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"A hot-air balloon floats because the heated air inside is less dense than the air outside: gross lift = envelope volume × (outside density − inside density). The hotter the envelope and the colder the day, the bigger the lift — which is why balloons fly best on cool mornings. Subtract the envelope, basket, burner and fuel to get the payload. Nylon limits the air to ~120 °C, capping the lift per cubic metre.","inputs":{"volume_m3":2500,"pressure_pa":101325,"ambient_temp_c":15,"internal_temp_c":100,"envelope_mass_kg":250},"gross_lift_n":6841.3,"gross_lift_kg":697.62,"net_payload_kg":447.62,"ambient_density_kg_m3":1.225,"internal_density_kg_m3":0.946},"meta":{"timestamp":"2026-06-07T08:18:01.372Z","request_id":"1015b817-c6f6-4593-9e78-23f7369939a4"},"status":"ok","message":"Balloon lift","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/required-temp":{"get":{"operationId":"get_v1_required_temp","tags":["Balloon"],"summary":"Envelope temperature for a target lift","description":"","parameters":[{"name":"volume_m3","in":"query","required":true,"description":"Envelope volume (m³)","schema":{"type":"string"},"example":"2500"},{"name":"ambient_temp_c","in":"query","required":true,"description":"Outside air temperature (°C)","schema":{"type":"string"},"example":"15"},{"name":"required_lift_kg","in":"query","required":true,"description":"Required gross lift (kg)","schema":{"type":"string"},"example":"600"},{"name":"pressure_pa","in":"query","required":false,"description":"Air pressure (Pa, default 101325)","schema":{"type":"string"},"example":"101325"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"To carry a target gross lift the inside air must drop to a density of outside − lift ÷ volume, which fixes the envelope temperature via the ideal-gas law. If that comes out above ~120 °C the standard nylon envelope cannot take it — you need a bigger envelope, a lighter load or a cooler/denser-air day. This is the everyday pre-flight check: can the balloon lift the planned crew and fuel today?","inputs":{"volume_m3":2500,"pressure_pa":101325,"ambient_temp_c":15,"required_lift_kg":600},"feasible_for_nylon":true,"required_internal_temp_c":85.2,"required_internal_density_kg_m3":0.985},"meta":{"timestamp":"2026-06-07T08:18:01.472Z","request_id":"fb0a3af6-d8c5-4451-a81a-f584ce1a23fd"},"status":"ok","message":"Required temperature","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":"SI (m³, °C, Pa, kg, N). lift = V·(ρ_out − ρ_in); ρ = (P − 0.378·Pv)/(287.05·T). Nylon limits ~120 °C. For Archimedes flotation in water use a buoyancy API; for party-balloon helium lift a balloon API.","service":"hotairballoon-api","endpoints":{"GET /v1/lift":"Gross and net lift from volume and the temperature difference.","GET /v1/meta":"This document.","GET /v1/air-density":"Moist-air density from temperature, pressure and humidity.","GET /v1/required-temp":"Envelope temperature needed for a target lift."},"description":"Hot-air-balloon lift maths: thermal buoyant lift, the envelope temperature for a target lift, and moist-air density."},"meta":{"timestamp":"2026-06-07T08:18:01.551Z","request_id":"c4b60b27-6033-4081-b02a-050d4d25de79"},"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":9400,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":680,"monthly_call_quota":91000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2500,"monthly_call_quota":372000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7700,"monthly_call_quota":1700000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/hotairballoon-api"}