# Pendulum Calculator API
> Gravity-driven pendulum maths as an API, computed locally and deterministically. The simple endpoint computes the period of a simple pendulum, T = 2π·√(L/g), together with its frequency and angular frequency, and solves for the length needed to give a target period — with an optional large-amplitude correction (the first two terms of the amplitude series) for swings where the small-angle approximation no longer holds. The physical endpoint handles a compound (physical) pendulum — any rigid body swinging about a pivot — from its moment of inertia about the pivot, its mass and the distance from the pivot to its centre of mass, T = 2π·√(I/(m·g·d)), and reports the equivalent simple-pendulum length I/(m·d). The conical endpoint solves a conical pendulum, a bob sweeping a horizontal circle, T = 2π·√(L·cosθ/g), giving the radius of the circle, the speed of the bob, the angular velocity and — with a mass — the string tension m·g/cosθ and the centripetal force. Everything is an idealised system under constant gravity with no air resistance or string mass, computed locally and deterministically, so it is instant and private. Ideal for physics-education and engineering tools, clock and metronome design, swing and amusement-ride dynamics, and STEM teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is gravity-pendulum dynamics; for spring-mass-damper vibration use a vibration API, for rotational kinetic energy use a flywheel 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/pendulum-api/..."
```

## Pricing
- **Free** (Free) — 2,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) — 779,000 calls/Mo, 40 req/s

## Endpoints

### Pendulum

#### `GET /v1/conical` — Conical pendulum

**Parameters:**
- `length` (query, required, string) — String length L (m) Example: `1`
- `angle` (query, required, string) — Angle from vertical (degrees) Example: `30`
- `mass` (query, optional, string) — Bob mass (kg) for tension & force Example: `1`
- `gravity` (query, optional, string) — Gravity g (m/s², default 9.81) Example: `9.81`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pendulum-api/v1/conical?length=1&angle=30&mass=1&gravity=9.81"
```

**Response:**
```json
{
    "data": {
        "note": "Bob swinging in a horizontal circle; the string traces a cone at the given angle from vertical.",
        "inputs": {
            "mass": 1,
            "length": 1,
            "gravity": 9.81,
            "angle_deg": 30
        },
        "period_s": 1.866855,
        "bob_speed": 1.682826,
        "frequency_hz": 0.53566,
        "circle_radius_m": 0.5,
        "angular_velocity": 3.365652,
        "string_tension_n": 11.327612,
        "centripetal_force_n": 5.663806
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.027Z",
        "request_id": "ee6419bc-7d9b-4184-a861-0d18bca982eb"
    },
    "status": "ok",
    "message": "Conical pendulum",
    "success": true
}
```

#### `GET /v1/physical` — Physical / compound pendulum

**Parameters:**
- `moment_of_inertia` (query, required, string) — Moment of inertia about the pivot (kg·m²) Example: `0.3333`
- `mass` (query, required, string) — Mass (kg) Example: `1`
- `distance` (query, required, string) — Pivot-to-centre-of-mass distance (m) Example: `0.5`
- `gravity` (query, optional, string) — Gravity g (m/s², default 9.81) Example: `9.81`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pendulum-api/v1/physical?moment_of_inertia=0.3333&mass=1&distance=0.5&gravity=9.81"
```

**Response:**
```json
{
    "data": {
        "note": "Compound pendulum swinging about a pivot a distance d from its centre of mass. The equivalent simple-pendulum length is I/(m·d).",
        "inputs": {
            "mass": 1,
            "gravity": 9.81,
            "distance": 0.5,
            "moment_of_inertia": 0.3333
        },
        "period_s": 1.637865,
        "frequency_hz": 0.610551,
        "angular_frequency": 3.836205,
        "equivalent_simple_length_m": 0.6666
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.139Z",
        "request_id": "8ea3f039-7b35-48c2-8b61-63758e4e298d"
    },
    "status": "ok",
    "message": "Physical pendulum",
    "success": true
}
```

#### `GET /v1/simple` — Simple pendulum

**Parameters:**
- `length` (query, optional, string) — Pendulum length L (m) Example: `1`
- `period` (query, optional, string) — Or a target period (s) to solve the length
- `amplitude` (query, optional, string) — Swing amplitude (degrees) for large-angle correction Example: `0`
- `gravity` (query, optional, string) — Gravity g (m/s², default 9.81) Example: `9.81`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pendulum-api/v1/simple?length=1&amplitude=0&gravity=9.81"
```

**Response:**
```json
{
    "data": {
        "note": "Small-angle (θ→0) period. Pass an 'amplitude' in degrees for the large-angle correction.",
        "inputs": {
            "length": 1,
            "gravity": 9.81,
            "amplitude_deg": 0
        },
        "period_s": 2.006067,
        "solved_for": null,
        "frequency_hz": 0.498488,
        "angular_frequency": 3.132092,
        "large_angle_period_s": 2.006067,
        "large_angle_correction_factor": 1
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.255Z",
        "request_id": "c568febb-7005-4197-891d-a273dac0dd5a"
    },
    "status": "ok",
    "message": "Simple pendulum",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Idealised, no air resistance or string mass. Default g = 9.81 m/s². The simple-pendulum period is the small-angle limit unless an amplitude is given.",
        "service": "pendulum-api",
        "formulae": {
            "simple": "T = 2π·√(L/g)",
            "conical": "T = 2π·√(L·cosθ/g),  r = L·sinθ,  tension = m·g/cosθ",
            "physical": "T = 2π·√(I/(m·g·d)),  L_eq = I/(m·d)"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/simple": "Simple pendulum period T = 2π√(L/g); solves length from a period; optional large-angle correction.",
            "GET /v1/conical": "Conical pendulum period, circle radius, bob speed and string tension.",
            "GET /v1/physical": "Physical/compound pendulum T = 2π√(I/(m·g·d)) and the equivalent simple-pendulum length."
        },
        "description": "Gravity-driven pendulum calculator: simple, physical (compound) and conical pendulum periods, frequencies and dynamics under constant gravity."
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.380Z",
        "request_id": "b516af10-1ae9-413f-abb1-c9e8c2311cba"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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