# Projectile Motion API
> Ballistic projectile-motion maths as an API, computed locally and deterministically. The launch endpoint takes a launch speed and angle (and, optionally, a launch height above the landing plane and a custom gravity) and returns the full flight: the horizontal and initial vertical velocity components, the time of flight, the range, the maximum height, the time to the apex and the impact speed and angle — using R = v0²·sin(2θ)/g on flat ground and solving the full quadratic h0 + vy0·t − ½g·t² = 0 when launched from a height. The trajectory endpoint gives the exact state of the projectile — its x and y position, its horizontal and vertical velocity, its speed and its direction — at any given time t or at any given horizontal distance x. The range endpoint works backwards: from a target range it solves the two complementary launch angles that reach it for a given speed (the flat fast shot and the high lob), or the launch speed needed at a chosen angle, and reports the maximum achievable range. Everything is an idealised point mass under constant gravity with no air resistance, computed locally and deterministically, so it is instant and private. Ideal for physics-education and ballistics tools, game and simulation development, sports-trajectory and artillery-style calculators, and STEM teaching. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is ballistic projectile kinematics; for orbital mechanics use an orbital API, for universal gravitation use a gravitation 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/projectile-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) — 756,000 calls/Mo, 40 req/s

## Endpoints

### Projectile

#### `GET /v1/launch` — Launch summary

**Parameters:**
- `velocity` (query, required, string) — Launch speed v0 (m/s) Example: `20`
- `angle` (query, required, string) — Launch angle (degrees, -90..90) Example: `45`
- `height` (query, optional, string) — Launch height above landing plane (m, default 0) 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/projectile-api/v1/launch?velocity=20&angle=45&height=0&gravity=9.81"
```

**Response:**
```json
{
    "data": {
        "note": "Flat ground: launch and landing at the same level.",
        "inputs": {
            "gravity": 9.81,
            "velocity": 20,
            "angle_deg": 45,
            "launch_height": 0
        },
        "range_m": 40.77472,
        "impact_speed": 20,
        "max_height_m": 10.19368,
        "time_to_apex_s": 1.441604,
        "impact_angle_deg": -45,
        "time_of_flight_s": 2.883208,
        "horizontal_velocity": 14.142136,
        "vertical_velocity_initial": 14.142136
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.511Z",
        "request_id": "c0742896-dbe4-47f2-900a-34a387938d5f"
    },
    "status": "ok",
    "message": "Projectile launch summary",
    "success": true
}
```

#### `GET /v1/range` — Solve range / angle / speed

**Parameters:**
- `range` (query, required, string) — Target range (m) Example: `50`
- `velocity` (query, optional, string) — Launch speed to solve the angle (m/s) Example: `30`
- `angle` (query, optional, string) — Or launch angle to solve the speed (degrees)
- `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/projectile-api/v1/range?range=50&velocity=30&gravity=9.81"
```

**Response:**
```json
{
    "data": {
        "mode": "solve_angle",
        "note": "Two launch angles reach the same range (complementary). The low angle is flatter/faster, the high angle is a lob.",
        "inputs": {
            "range": 50,
            "gravity": 9.81,
            "velocity": 30
        },
        "max_range_m": 91.743119,
        "angle_low_deg": 16.512332,
        "angle_high_deg": 73.487668
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.616Z",
        "request_id": "6b6f2746-ab73-43f1-a93c-aaeb7ae3ded8"
    },
    "status": "ok",
    "message": "Solve range/angle/speed",
    "success": true
}
```

#### `GET /v1/trajectory` — Trajectory state

**Parameters:**
- `velocity` (query, required, string) — Launch speed v0 (m/s) Example: `20`
- `angle` (query, required, string) — Launch angle (degrees) Example: `45`
- `height` (query, optional, string) — Launch height (m, default 0) Example: `0`
- `gravity` (query, optional, string) — Gravity g (m/s², default 9.81) Example: `9.81`
- `time` (query, optional, string) — Evaluate at time t (s) Example: `1`
- `distance` (query, optional, string) — Or evaluate at horizontal distance x (m)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/projectile-api/v1/trajectory?velocity=20&angle=45&height=0&gravity=9.81&time=1"
```

**Response:**
```json
{
    "data": {
        "x_m": 14.142136,
        "y_m": 9.237136,
        "speed": 14.790788,
        "inputs": {
            "time": 1,
            "gravity": 9.81,
            "distance": null,
            "velocity": 20,
            "angle_deg": 45,
            "launch_height": 0
        },
        "time_s": 1,
        "velocity_x": 14.142136,
        "velocity_y": 4.332136,
        "below_ground": false,
        "direction_deg": 17.031306
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.717Z",
        "request_id": "713a168d-53a8-4a48-9ca7-04e646af05de"
    },
    "status": "ok",
    "message": "Trajectory state",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Idealised point mass, constant gravity, no air drag. Default g = 9.81 m/s².",
        "service": "projectile-api",
        "formulae": {
            "range": "R = v0²·sin(2θ)/g (flat)",
            "position": "x = v0cosθ·t,  y = h0 + v0sinθ·t − ½g·t²",
            "max_height": "H = h0 + vy0²/(2g)",
            "flight_time": "t = [vy0 + √(vy0² + 2g·h0)] / g"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/range": "Solve the launch angle for a target range (two solutions) or the speed for a target range at an angle.",
            "GET /v1/launch": "Flight time, range, max height, impact speed & angle from speed + angle (+ launch height, gravity).",
            "GET /v1/trajectory": "Position and velocity at a given time t or horizontal distance x."
        },
        "description": "Ballistic projectile-motion calculator: launch summary, trajectory state, and range/angle/speed solving under constant gravity (no air resistance)."
    },
    "meta": {
        "timestamp": "2026-06-04T10:18:37.830Z",
        "request_id": "a5a80aa0-c369-4c6b-840b-0c6720b05717"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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