# Tidal Forces API
> Tidal-physics and gravitational-dominance astrophysics as an API, computed locally and deterministically. The tidal-force endpoint computes the tidal (differential) acceleration that stretches a body, a = 2·G·M·r/d³, from the primary mass, the radius (half-size) of the affected body and the centre-to-centre distance — and the force if a body mass is given; tidal effects fall off as the inverse cube of distance, far faster than gravity's inverse square, which is why they matter only close in. The roche-limit endpoint computes the Roche limit, the distance inside which tidal forces tear a satellite apart, for both rigid bodies, d = R·(2·ρM/ρm)^(1/3), and fluid bodies, d = 2.44·R·(ρM/ρm)^(1/3), from the primary radius and the two densities — Saturn's rings sit inside its Roche limit. The hill-sphere endpoint computes the Hill-sphere radius, r_H ≈ a·(1−e)·(m/3M)^(1/3), the region where a body's own gravity dominates so it can keep moons, from the orbital distance, eccentricity and the two masses. Masses are in kilograms, distances and radii in metres and densities in kg/m³, with G = 6.674×10⁻¹¹. Everything is computed locally and deterministically, so it is instant and private. Ideal for astronomy, astrophysics, planetary-science, simulation and education app developers, ring-system and moon-stability tools, and physics education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is tidal and gravitational-dominance physics; for Newtonian gravity use a gravitation API and for orbital periods an orbital-mechanics 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/tidal-api/..."
```

## Pricing
- **Free** (Free) — 3,700 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 35,000 calls/Mo, 6 req/s
- **Pro** ($14/Mo) — 214,000 calls/Mo, 15 req/s
- **Mega** ($44/Mo) — 1,295,000 calls/Mo, 40 req/s

## Endpoints

### Tidal

#### `GET /v1/hill-sphere` — Hill sphere

**Parameters:**
- `orbital_distance` (query, required, string) — Orbital distance a (m) Example: `1.496e11`
- `body_mass` (query, required, string) — Body mass m (kg) Example: `5.972e24`
- `primary_mass` (query, required, string) — Primary mass M (kg) Example: `1.989e30`
- `eccentricity` (query, optional, string) — Eccentricity Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tidal-api/v1/hill-sphere?orbital_distance=1.496e11&body_mass=5.972e24&primary_mass=1.989e30&eccentricity=0"
```

**Response:**
```json
{
    "data": {
        "note": "Hill sphere r_H ≈ a·(1−e)·(m/3M)^(1/3) — the region where a body's gravity dominates over the primary's, so it can hold moons. Earth's Hill sphere is about 1.5 million km.",
        "inputs": {
            "body_mass": 5.972e+24,
            "eccentricity": 0,
            "primary_mass": 1.989e+30,
            "orbital_distance": 149600000000
        },
        "hill_radius_m": 1496417737.0931,
        "hill_radius_km": 1496417.7371
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:33.973Z",
        "request_id": "ecca9d55-eb41-4ba9-a474-fa0607b9f1d4"
    },
    "status": "ok",
    "message": "Hill sphere",
    "success": true
}
```

#### `GET /v1/roche-limit` — Roche limit

**Parameters:**
- `primary_radius` (query, required, string) — Primary radius R (m) Example: `6.371e6`
- `primary_density` (query, required, string) — Primary density (kg/m³) Example: `5514`
- `satellite_density` (query, required, string) — Satellite density (kg/m³) Example: `3344`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tidal-api/v1/roche-limit?primary_radius=6.371e6&primary_density=5514&satellite_density=3344"
```

**Response:**
```json
{
    "data": {
        "note": "Roche limit — inside it tidal forces tear a satellite apart. Rigid bodies: d = R·(2·ρM/ρm)^(1/3); fluid bodies: d = 2.44·R·(ρM/ρm)^(1/3). Saturn's rings lie inside its Roche limit.",
        "inputs": {
            "primary_radius": 6371000,
            "primary_density": 5514,
            "satellite_density": 3344
        },
        "roche_limit_fluid_m": 18365281.7634,
        "roche_limit_rigid_m": 9483116.8365,
        "roche_limit_fluid_km": 18365.2818,
        "roche_limit_rigid_km": 9483.1168
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:34.062Z",
        "request_id": "9ca5cb91-121f-4171-b3ae-6f6608a0745d"
    },
    "status": "ok",
    "message": "Roche limit",
    "success": true
}
```

#### `GET /v1/tidal-force` — Tidal acceleration

**Parameters:**
- `primary_mass` (query, required, string) — Primary mass M (kg) Example: `7.342e22`
- `body_radius` (query, required, string) — Affected-body radius r (m) Example: `6.371e6`
- `distance` (query, required, string) — Centre-to-centre distance d (m) Example: `3.844e8`
- `body_mass` (query, optional, string) — Affected-body mass (kg) for force

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tidal-api/v1/tidal-force?primary_mass=7.342e22&body_radius=6.371e6&distance=3.844e8"
```

**Response:**
```json
{
    "data": {
        "note": "Tidal (differential) acceleration across a body a = 2·G·M·r/d³ — the stretch between the near and far sides. It falls off as 1/d³, far faster than gravity's 1/d².",
        "inputs": {
            "distance": 384400000,
            "body_radius": 6371000,
            "primary_mass": 7.342e+22
        },
        "tidal_acceleration_ms2": 1.0992780787710049e-6
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:34.170Z",
        "request_id": "c95912f8-6c24-4692-bdc9-abc830e05ff9"
    },
    "status": "ok",
    "message": "Tidal acceleration",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Masses in kg, distances and radii in m, densities in kg/m³. G = 6.674×10⁻¹¹. Tidal effects scale as 1/d³.",
        "service": "tidal-api",
        "formulae": {
            "hill": "r_H = a·(1−e)·(m/3M)^(1/3)",
            "tidal": "a = 2·G·M·r/d³",
            "roche_fluid": "d = 2.44·R·(ρM/ρm)^(1/3)",
            "roche_rigid": "d = R·(2·ρM/ρm)^(1/3)"
        },
        "constants": {
            "gravitational_constant": 6.6743e-11
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/hill-sphere": "Hill-sphere radius from the orbital distance and the two masses.",
            "GET /v1/roche-limit": "Roche limit (rigid and fluid) from the primary radius and the two densities.",
            "GET /v1/tidal-force": "Tidal (differential) acceleration a = 2·G·M·r/d³, and force if a body mass is given."
        },
        "description": "Tidal-physics and gravitational-dominance calculator: tidal acceleration across a body, the Roche limit (rigid and fluid) and the Hill-sphere radius."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:34.266Z",
        "request_id": "fdc8a0a7-cfb3-46ae-b269-883e05bdacd2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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