# Gravitation & Weight API
> Newtonian gravitation as an API, computed locally and deterministically. The force endpoint applies Newton's law of universal gravitation, F = G·m1·m2/r² — the attractive force between two masses a distance apart, with G = 6.6743×10⁻¹¹ — and solves for whichever of the two masses, the separation or the force you leave out (the Earth and Moon pull on each other with about 2×10²⁰ newtons). The field endpoint gives the gravitational field strength g = G·M/r² at a distance from a mass, or the surface gravity of a built-in body (the Sun, the planets, the Moon and major moons), as a multiple of Earth gravity, and the weight of a test mass placed there. The weight endpoint tells you what something weighs on another world, W = m·g_body — your weight on the Moon, Mars or Jupiter — from a mass or your Earth weight, with the ratio to Earth. Everything is computed locally and deterministically, so it is instant and private. Ideal for physics and astronomy-education tools, space and planetary apps, science museums and games, and engineering. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is gravitational force, field and weight; for orbital speed, period and escape velocity use 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/gravitation-api/..."
```

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

## Endpoints

### Gravitation

#### `GET /v1/field` — Gravitational field strength

**Parameters:**
- `mass` (query, optional, string) — Central mass M (kg) Example: `5.972e24`
- `distance` (query, optional, string) — Distance r (m) Example: `6.371e6`
- `body` (query, optional, string) — Or a body (earth, moon, mars…)
- `test_mass` (query, optional, string) — Test mass (kg) for its weight

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravitation-api/v1/field?mass=5.972e24&distance=6.371e6"
```

**Response:**
```json
{
    "data": {
        "formula": "g = G·M/r²; weight W = m·g.",
        "g_force": 1.001359,
        "field_source": "G·M/r²",
        "gravitational_field_ms2": 9.81997343
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:41.129Z",
        "request_id": "1ca5770b-de00-4b44-9386-ff0b53986b18"
    },
    "status": "ok",
    "message": "Gravitational field strength",
    "success": true
}
```

#### `GET /v1/force` — Newton's law of gravitation

**Parameters:**
- `mass1` (query, optional, string) — Mass 1 (kg) Example: `5.972e24`
- `mass2` (query, optional, string) — Mass 2 (kg) Example: `7.348e22`
- `distance` (query, optional, string) — Separation r (m) Example: `3.844e8`
- `force` (query, optional, string) — Or force (N) to solve another

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravitation-api/v1/force?mass1=5.972e24&mass2=7.348e22&distance=3.844e8"
```

**Response:**
```json
{
    "data": {
        "formula": "F = G·m1·m2/r²; G = 6.6743×10⁻¹¹ N·m²/kg².",
        "mass1_kg": 5.972e+24,
        "mass2_kg": 7.348e+22,
        "distance_m": 384400000,
        "gravitational_force_n": 1.982110729079252e+20,
        "gravitational_constant": 6.6743e-11
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:41.217Z",
        "request_id": "3680871f-7f33-4ec1-9a79-7d9a428c1345"
    },
    "status": "ok",
    "message": "Gravitational force",
    "success": true
}
```

#### `GET /v1/weight` — Weight on a body

**Parameters:**
- `body` (query, required, string) — Body (earth, moon, mars, jupiter…) Example: `mars`
- `mass` (query, optional, string) — Mass (kg) Example: `70`
- `earth_weight` (query, optional, string) — Or your weight on Earth (N)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravitation-api/v1/weight?body=mars&mass=70"
```

**Response:**
```json
{
    "data": {
        "body": "mars",
        "formula": "W = m·g_body; ratio = g_body/g_earth.",
        "mass_kg": 70,
        "weight_n": 259.7,
        "weight_kgf": 26.48203,
        "ratio_to_earth": 0.378315,
        "weight_on_earth_n": 686.4655,
        "surface_gravity_ms2": 3.71
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:41.308Z",
        "request_id": "99494b52-88de-4382-a812-40e4d66e4111"
    },
    "status": "ok",
    "message": "Weight on a body",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "gravitation",
        "note": "Newtonian gravitation (force, field, weight) — computed locally and deterministically, no key, no third-party service.",
        "bodies": [
            "sun",
            "mercury",
            "venus",
            "earth",
            "moon",
            "mars",
            "jupiter",
            "saturn",
            "uranus",
            "neptune",
            "pluto",
            "ceres",
            "europa",
            "titan",
            "io"
        ],
        "constants": {
            "gravitational_constant": 6.6743e-11
        },
        "endpoints": [
            "/v1/force",
            "/v1/field",
            "/v1/weight",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:41.393Z",
        "request_id": "89cf1575-9dec-434e-91e8-e251820f6c9d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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