# Orbital Mechanics API
> Orbital-mechanics maths as an API, computed locally and deterministically. The circular endpoint computes a circular orbit around a body — the orbital speed v = √(GM/r), the orbital period T = 2π·√(r³/GM), the escape speed and the specific orbital energy — from a built-in body (Sun, Mercury through Neptune, the Moon) and an altitude above its surface, or from an explicit orbital radius, central mass or standard gravitational parameter. The escape endpoint gives the escape velocity √(2·GM/r) at any radius or altitude, which is √2 times the circular-orbit speed there. The period endpoint applies Kepler's third law in both directions: from a semi-major axis it returns the orbital period, and from a period it returns the semi-major axis — so a sidereal day around Earth gives the geostationary radius of about 42,164 km. Speeds come out in metres and kilometres per second and km/h, distances in metres and kilometres, and periods in seconds, minutes, hours and days. Everything is computed in SI and is instant and private. Ideal for aerospace and satellite tools, space-mission and education apps, astronomy and KSP-style games, and physics calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is orbital mechanics; for live satellite catalogues use a satellites API and for sky positions use an astronomy 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/orbital-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 25,000 calls/Mo, 5 req/s
- **Pro** ($15/Mo) — 150,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 786,000 calls/Mo, 40 req/s

## Endpoints

### Orbital

#### `GET /v1/circular` — Circular orbit speed & period

**Parameters:**
- `body` (query, optional, string) — sun|earth|moon|mars|… (or mass/gm) Example: `earth`
- `mass` (query, optional, string) — Or central mass (kg)
- `gm` (query, optional, string) — Or standard gravitational parameter
- `altitude` (query, optional, string) — Altitude above surface (m) Example: `400000`
- `orbital_radius` (query, optional, string) — Or orbital radius (m)
- `body_radius` (query, optional, string) — Body radius (m, with mass/gm + altitude)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/orbital-api/v1/circular?body=earth&altitude=400000"
```

**Response:**
```json
{
    "data": {
        "gm": 398600441800000,
        "formula": "v = √(GM/r); T = 2π·√(r³/GM); escape = v·√2.",
        "altitude": {
            "m": 400000,
            "km": 400
        },
        "central_body": "earth",
        "escape_speed": {
            "m_s": 10850.693,
            "km_h": 39062.5,
            "km_s": 10.85069
        },
        "orbit_radius": {
            "m": 6771000,
            "km": 6771
        },
        "orbital_speed": {
            "m_s": 7672.599,
            "km_h": 27621.36,
            "km_s": 7.6726
        },
        "orbital_period": {
            "days": 0.064177,
            "hours": 1.54024,
            "minutes": 92.4143,
            "seconds": 5544.86
        },
        "specific_orbital_energy_J_per_kg": -29434385.0096
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:01.907Z",
        "request_id": "4a40e003-ca9b-4513-971b-ef49c945cbfe"
    },
    "status": "ok",
    "message": "Circular orbit speed & period",
    "success": true
}
```

#### `GET /v1/escape` — Escape velocity

**Parameters:**
- `body` (query, optional, string) — Body (or mass/gm) Example: `earth`
- `mass` (query, optional, string) — Or central mass (kg)
- `gm` (query, optional, string) — Or GM
- `altitude` (query, optional, string) — Altitude above surface (m) Example: `0`
- `orbital_radius` (query, optional, string) — Or radius (m)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/orbital-api/v1/escape?body=earth&altitude=0"
```

**Response:**
```json
{
    "data": {
        "gm": 398600441800000,
        "note": "Escape speed is √2 times the circular-orbit speed at the same radius.",
        "radius": {
            "m": 6371000,
            "km": 6371
        },
        "formula": "escape = √(2·GM/r).",
        "altitude": {
            "m": 0,
            "km": 0
        },
        "central_body": "earth",
        "escape_speed": {
            "m_s": 11186.136,
            "km_h": 40270.09,
            "km_s": 11.18614
        },
        "circular_speed": {
            "m_s": 7909.792,
            "km_h": 28475.25,
            "km_s": 7.90979
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:01.994Z",
        "request_id": "c704bb60-e53b-46e3-ad62-a57a24a44713"
    },
    "status": "ok",
    "message": "Escape velocity",
    "success": true
}
```

#### `GET /v1/period` — Kepler period ↔ semi-major axis

**Parameters:**
- `body` (query, optional, string) — Body (or mass/gm) Example: `earth`
- `mass` (query, optional, string) — Or central mass (kg)
- `gm` (query, optional, string) — Or GM
- `semi_major_axis` (query, optional, string) — Semi-major axis (m, to get period)
- `period` (query, optional, string) — Or period (s, to get axis) Example: `86164`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/orbital-api/v1/period?body=earth&period=86164"
```

**Response:**
```json
{
    "data": {
        "gm": 398600441800000,
        "mode": "period_to_axis",
        "note": "For Earth (T = 86164 s, one sidereal day) this gives the geostationary radius (~42,164 km).",
        "formula": "a = (GM·T² / 4π²)^(1/3).",
        "altitude": {
            "m": 35793140.1,
            "km": 35793.14
        },
        "central_body": "earth",
        "orbital_period": {
            "days": 0.997269,
            "hours": 23.93444,
            "minutes": 1436.0667,
            "seconds": 86164
        },
        "semi_major_axis": {
            "m": 42164140.1,
            "km": 42164.14
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.072Z",
        "request_id": "f38c5a41-a0d9-4e84-b21c-8950da182ff8"
    },
    "status": "ok",
    "message": "Kepler period <-> semi-major axis",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "orbital",
        "note": "Orbital-mechanics maths — computed locally and deterministically, no key, no third-party service. SI units (metres, seconds).",
        "bodies": [
            "sun",
            "mercury",
            "venus",
            "earth",
            "moon",
            "mars",
            "jupiter",
            "saturn",
            "uranus",
            "neptune"
        ],
        "endpoints": [
            "/v1/circular",
            "/v1/escape",
            "/v1/period",
            "/v1/meta"
        ],
        "gravitational_constant": 6.6743e-11
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:02.172Z",
        "request_id": "f63a3fcf-5773-4e06-9477-70958bbb190e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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