# Archery & Arrow API
> Archery and arrow maths as an API, computed locally and deterministically — the FOC, energy and arrow-weight numbers an archer or bowhunter tunes a setup with. The FOC endpoint finds the front-of-center balance, the share of an arrow’s weight that sits forward of the middle: FOC = ((balance point − length ÷ 2) ÷ length) × 100 measured from the throat of the nock, so a 28-inch arrow balancing at 16 inches is 7.1 % — and it bands the result, since target archers run about 7–12 % while hunters push 12–19 % for penetration and forgiveness. The energy endpoint turns arrow weight and speed into terminal performance: kinetic energy (ft-lb) = grains × fps² ÷ 450,240 and momentum (slug-fps) = grains × fps ÷ 225,218, so a 400-grain arrow at 280 fps carries about 69.7 ft-lb and 0.50 slug-fps, with a suggested game class — momentum, not KE, is the better penetration predictor for heavy arrows. The weight endpoint totals a finished arrow from its parts — shaft (grains-per-inch × length) plus point, insert, nock and fletching — and divides by draw weight for grains-per-pound, flagging the 5-GPP minimum that protects the bow. Everything is computed locally and deterministically, so it is instant and private. Ideal for archery, bowhunting, traditional-archery and outdoor-sports app developers, arrow-builder and bow-tuning tools, and pro-shop calculators. Pure local computation — no key, no third-party service, instant. Imperial archery units. Live, nothing stored. 3 compute endpoints. For sight marks or bow tuning use a different 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/archery-api/..."
```

## Pricing
- **Free** (Free) — 7,050 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 55,500 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 228,500 calls/Mo, 15 req/s
- **Mega** ($38/Mo) — 1,325,000 calls/Mo, 40 req/s

## Endpoints

### Archery

#### `GET /v1/energy` — Kinetic energy + momentum

**Parameters:**
- `arrow_grains` (query, required, string) — Total arrow weight (grains) Example: `400`
- `speed_fps` (query, required, string) — Arrow speed (fps) Example: `280`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/archery-api/v1/energy?arrow_grains=400&speed_fps=280"
```

**Response:**
```json
{
    "data": {
        "note": "KE (ft-lb) = grains × fps² ÷ 450,240. Momentum (slug-fps) = grains × fps ÷ 225,218. Momentum predicts penetration better than KE for heavy arrows. Common bowhunting guidance: 25+ ft-lb deer, 40+ elk.",
        "inputs": {
            "speed_fps": 280,
            "arrow_grains": 400
        },
        "suggested_game": "tough/dangerous game",
        "momentum_slug_fps": 0.4973,
        "kinetic_energy_ftlb": 69.65
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:04.909Z",
        "request_id": "6b1301ff-fd41-4743-a52e-2f3792db1ac5"
    },
    "status": "ok",
    "message": "Kinetic energy",
    "success": true
}
```

#### `GET /v1/foc` — Front-of-center balance

**Parameters:**
- `arrow_length_in` (query, required, string) — Overall arrow length (in) Example: `28`
- `balance_point_in` (query, required, string) — Balance point from nock throat (in) Example: `16`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/archery-api/v1/foc?arrow_length_in=28&balance_point_in=16"
```

**Response:**
```json
{
    "data": {
        "band": "normal (target / general 7–12 %)",
        "note": "FOC = ((balance point − arrow length ÷ 2) ÷ arrow length) × 100, balance measured from the throat of the nock. Target archers run ~7–12 %, hunters 12–19 % for better penetration and forgiveness.",
        "inputs": {
            "arrow_length_in": 28,
            "balance_point_in": 16
        },
        "center_in": 14,
        "foc_percent": 7.14
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:05.009Z",
        "request_id": "c45e8d23-4f27-4cc3-8453-7c0b050ac02d"
    },
    "status": "ok",
    "message": "Arrow FOC",
    "success": true
}
```

#### `GET /v1/weight` — Total arrow weight + GPP

**Parameters:**
- `shaft_gpi` (query, required, string) — Shaft grains per inch Example: `9.3`
- `shaft_length_in` (query, required, string) — Shaft length (in) Example: `28`
- `point_grains` (query, optional, string) — Point weight (default 100) Example: `100`
- `insert_grains` (query, optional, string) — Insert weight (default 20) Example: `20`
- `nock_grains` (query, optional, string) — Nock weight (default 10) Example: `10`
- `fletching_grains` (query, optional, string) — Total fletching weight (default 21) Example: `21`
- `draw_weight_lb` (query, optional, string) — Bow draw weight (gives GPP) Example: `60`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/archery-api/v1/weight?shaft_gpi=9.3&shaft_length_in=28&point_grains=100&insert_grains=20&nock_grains=10&fletching_grains=21&draw_weight_lb=60"
```

**Response:**
```json
{
    "data": {
        "note": "Total = shaft (GPI × length) + point + insert + nock + fletching. Grains-per-pound (GPP) = total ÷ draw weight; keep GPP ≥ 5 to protect the bow, ~5–6.5 for hunting penetration.",
        "safe": true,
        "inputs": {
            "shaft_gpi": 9.3,
            "nock_grains": 10,
            "point_grains": 100,
            "insert_grains": 20,
            "shaft_length_in": 28,
            "fletching_grains": 21
        },
        "shaft_grains": 260.4,
        "draw_weight_lb": 60,
        "grains_per_pound": 6.86,
        "total_arrow_grains": 411.4,
        "front_weight_percent": 29.17
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:05.121Z",
        "request_id": "9996b6d1-9e0e-4e74-a194-0da29d0e6c3a"
    },
    "status": "ok",
    "message": "Arrow weight",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Imperial archery units: inches, grains, fps. KE = grains × fps² ÷ 450,240; momentum = grains × fps ÷ 225,218; FOC from the AMO method. For bow tuning or sight marks use a different API.",
        "service": "archery-api",
        "endpoints": {
            "GET /v1/foc": "Front-of-center balance percentage from arrow length and balance point.",
            "GET /v1/meta": "This document.",
            "GET /v1/energy": "Kinetic energy and momentum from arrow weight and speed.",
            "GET /v1/weight": "Total finished arrow weight from components, plus grains-per-pound."
        },
        "description": "Archery maths: arrow FOC balance, kinetic energy & momentum, and total arrow weight from components with grains-per-pound."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:05.224Z",
        "request_id": "abac72c2-4a28-4529-9a90-17a0494ee97f"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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