# Buoyancy & Flotation API
> Archimedes buoyancy and flotation maths as an API, computed locally and deterministically. The buoyancy endpoint computes the buoyant force on a submerged or floating body, Fb = ρ_fluid·g·V_displaced — the upthrust equals the weight of the displaced fluid — from a displaced volume and a fluid (water, seawater, oil, mercury and more, or a custom density), and also gives the mass of displaced fluid; it solves the volume from a known force too. The float endpoint decides whether an object floats, sinks or is neutrally buoyant by comparing its density (given directly, from a built-in material, or as mass divided by volume) with the fluid density, and for a floating object returns the fraction submerged f = ρ_object/ρ_fluid (so 90 % of an iceberg sits below the waterline), or for a sinking object its apparent (underwater) weight. The payload endpoint sizes flotation: the displaced volume needed to float a given load, V = W/(ρ_fluid·g), or the maximum extra payload a floating body of a given volume and density can carry before it submerges, Wmax = (ρ_fluid − ρ_body)·V·g. Everything is computed locally and deterministically, so it is instant and private. Ideal for naval-architecture and marine tools, diving, ROV and ballast apps, raft and pontoon design, and physics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is buoyancy and flotation; for pressure at depth and hydrostatic force on a wall use a hydrostatics API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/buoyancy-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($75/Mo) — 750,000 calls/Mo, 40 req/s

## Endpoints

### Buoyancy

#### `GET /v1/buoyancy` — Buoyant force

**Parameters:**
- `fluid` (query, optional, string) — water|seawater|oil|mercury… (default water) Example: `water`
- `fluid_density` (query, optional, string) — Or fluid density (kg/m³)
- `displaced_volume` (query, optional, string) — Displaced volume (m³) Example: `0.01`
- `buoyant_force` (query, optional, string) — Or buoyant force (N) to solve volume
- `gravity` (query, optional, string) — Gravity (default 9.80665)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoyancy-api/v1/buoyancy?fluid=water&displaced_volume=0.01"
```

**Response:**
```json
{
    "data": {
        "fluid": "water",
        "formula": "Fb = ρ_fluid · g · V_displaced.",
        "gravity_ms2": 9.80665,
        "buoyant_force_n": 98.0665,
        "buoyant_force_kgf": 10,
        "displaced_volume_m3": 0.01,
        "fluid_density_kg_m3": 1000,
        "displaced_fluid_mass_kg": 10,
        "displaced_volume_litres": 10
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:48.216Z",
        "request_id": "9da0b4e4-3025-4332-b91c-2c4befcb6ac4"
    },
    "status": "ok",
    "message": "Buoyant force",
    "success": true
}
```

#### `GET /v1/float` — Float-or-sink analysis

**Parameters:**
- `object_density` (query, optional, string) — Object density (kg/m³) Example: `600`
- `material` (query, optional, string) — Or a material (ice, oak, aluminium…)
- `mass` (query, optional, string) — Or mass (kg) with volume
- `volume` (query, optional, string) — Object volume (m³)
- `fluid` (query, optional, string) — Fluid (default water) Example: `water`
- `fluid_density` (query, optional, string) — Or fluid density (kg/m³)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoyancy-api/v1/float?object_density=600&fluid=water"
```

**Response:**
```json
{
    "data": {
        "fluid": "water",
        "state": "floats",
        "formula": "floats when ρ_object < ρ_fluid; fraction submerged = ρ_object/ρ_fluid.",
        "density_ratio": 0.6,
        "percent_submerged": 60,
        "fraction_submerged": 0.6,
        "fluid_density_kg_m3": 1000,
        "object_density_kg_m3": 600,
        "object_density_source": "given",
        "percent_above_surface": 40
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:48.325Z",
        "request_id": "f8fe0d9c-accf-486b-a53f-ec1265fc8ace"
    },
    "status": "ok",
    "message": "Float-or-sink analysis",
    "success": true
}
```

#### `GET /v1/payload` — Flotation load capacity

**Parameters:**
- `load_weight` (query, optional, string) — Load to float (N) Example: `1000`
- `load_mass` (query, optional, string) — Or load mass (kg)
- `volume` (query, optional, string) — Body volume (m³) for max payload
- `object_density` (query, optional, string) — Body density with volume
- `material` (query, optional, string) — Or body material
- `fluid` (query, optional, string) — Fluid (default water) Example: `water`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoyancy-api/v1/payload?load_weight=1000&fluid=water"
```

**Response:**
```json
{
    "data": {
        "mode": "required_volume",
        "fluid": "water",
        "formula": "V = W / (ρ_fluid·g).",
        "load_mass_kg": 101.971621,
        "load_weight_n": 1000,
        "fluid_density_kg_m3": 1000,
        "required_displaced_volume_m3": 0.101971621,
        "required_displaced_volume_litres": 101.971621
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:48.408Z",
        "request_id": "35ed4284-2e52-451d-845d-720d03a75676"
    },
    "status": "ok",
    "message": "Flotation load capacity",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/buoyancy-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "api": "buoyancy",
        "note": "Archimedes buoyancy / flotation — computed locally and deterministically, no key, no third-party service.",
        "fluids": [
            "water",
            "freshwater",
            "seawater",
            "saltwater",
            "oil",
            "gasoline",
            "petrol",
            "diesel",
            "ethanol",
            "glycerin",
            "mercury",
            "milk",
            "honey",
            "air"
        ],
        "endpoints": [
            "/v1/buoyancy",
            "/v1/float",
            "/v1/payload",
            "/v1/meta"
        ],
        "materials": [
            "ice",
            "oak",
            "pine",
            "balsa",
            "cork",
            "bamboo",
            "aluminium",
            "aluminum",
            "steel",
            "iron",
            "copper",
            "lead",
            "gold",
            "concrete",
            "glass",
            "rubber",
            "pvc",
            "polyethylene",
            "polystyrene",
            "styrofoam"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:48.508Z",
        "request_id": "0db14c24-43f8-4675-9f8a-ed5e3e6436e5"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/buoyancy-api
OpenAPI spec: https://www.oanor.com/api/buoyancy-api/openapi.json