# Golf Scoring API
> Golf scoring and handicap maths as an API, computed locally and deterministically — the World Handicap System and Stableford numbers a golfer, club or scoring app works to. The handicap endpoint computes the course handicap from a handicap index: course handicap = index × (slope rating ÷ 113) + (course rating − par), rounded, so a 14.5 index on a 130-slope, 71.5-rated par-72 course plays off 16; it also applies the format allowance (e.g. 95 % for stroke play) to give the playing handicap. The stableford endpoint scores a hole on the standard scale: net par is 2 points, each stroke better adds one (birdie 3, eagle 4) and each worse subtracts one (bogey 1), with net double bogey or worse scoring 0, where the net score is the gross minus the strokes received on that hole. The net endpoint gives the round's net score — gross total minus the course handicap — against par. Everything is computed locally and deterministically, so it is instant and private. Ideal for golf, club-management, scoring and sports app developers, handicap and Stableford tools, and golf education. Pure local computation — no key, no third-party service, instant. Slope defaults to the neutral 113. Live, nothing stored. 3 compute endpoints. A scoring aid, not an official handicap record.

## 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/golf-api/..."
```

## Pricing
- **Free** (Free) — 6,250 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 57,500 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 241,000 calls/Mo, 15 req/s
- **Mega** ($40/Mo) — 1,355,000 calls/Mo, 40 req/s

## Endpoints

### Golf

#### `GET /v1/handicap` — WHS course handicap

**Parameters:**
- `handicap_index` (query, required, string) — Handicap index Example: `14.5`
- `slope_rating` (query, optional, string) — Slope rating (default 113) Example: `130`
- `course_rating` (query, optional, string) — Course rating Example: `71.5`
- `par` (query, optional, string) — Par (default 72) Example: `72`
- `allowance_percent` (query, optional, string) — Handicap allowance % (default 100) Example: `95`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/golf-api/v1/handicap?handicap_index=14.5&slope_rating=130&course_rating=71.5&par=72&allowance_percent=95"
```

**Response:**
```json
{
    "data": {
        "note": "WHS course handicap = Handicap Index × (Slope ÷ 113) + (Course Rating − Par), rounded. Playing handicap applies the format's allowance (e.g. 95% for stroke play, 90% singles match).",
        "inputs": {
            "par": 72,
            "slope_rating": 130,
            "course_rating": 71.5,
            "handicap_index": 14.5,
            "allowance_percent": 95
        },
        "course_handicap": 16,
        "playing_handicap": 15,
        "course_handicap_raw": 16.181
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:08.362Z",
        "request_id": "68e34bf1-6f56-4f0e-85ed-5ff4e49bb536"
    },
    "status": "ok",
    "message": "Course handicap",
    "success": true
}
```

#### `GET /v1/net` — Net score (round)

**Parameters:**
- `gross_total` (query, required, string) — Gross total for the round Example: `90`
- `course_handicap` (query, required, string) — Course handicap Example: `16`
- `par` (query, optional, string) — Course par (default 72) Example: `72`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/golf-api/v1/net?gross_total=90&course_handicap=16&par=72"
```

**Response:**
```json
{
    "data": {
        "note": "Net score = gross total − course handicap. Compare net to par to see the handicap-adjusted result for the round.",
        "inputs": {
            "par": 72,
            "gross_total": 90,
            "course_handicap": 16
        },
        "net_score": 74,
        "net_to_par": 2,
        "gross_to_par": 18
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:08.451Z",
        "request_id": "60c18bc4-7b25-497f-a0ee-edcccea3420c"
    },
    "status": "ok",
    "message": "Net score",
    "success": true
}
```

#### `GET /v1/stableford` — Stableford points (hole)

**Parameters:**
- `gross` (query, required, string) — Gross strokes on the hole Example: `5`
- `par` (query, required, string) — Hole par Example: `4`
- `strokes_received` (query, optional, string) — Strokes received on the hole Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/golf-api/v1/stableford?gross=5&par=4&strokes_received=1"
```

**Response:**
```json
{
    "data": {
        "note": "Stableford: net par scores 2 points, each stroke better +1 (birdie 3, eagle 4), each worse −1 (bogey 1), and net double bogey or worse scores 0. Net score = gross − strokes received.",
        "inputs": {
            "par": 4,
            "gross": 5,
            "strokes_received": 1
        },
        "result": "par",
        "net_score": 4,
        "net_to_par": 0,
        "stableford_points": 2
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:08.531Z",
        "request_id": "acf1e80d-d6fe-46fc-b0d6-4b1167654b11"
    },
    "status": "ok",
    "message": "Stableford points",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Slope defaults to 113 (the neutral rating). Stableford uses the standard 2-points-for-net-par scale. A scoring aid, not an official handicap record.",
        "service": "golf-api",
        "endpoints": {
            "GET /v1/net": "Net score for a round from the gross total and course handicap.",
            "GET /v1/meta": "This document.",
            "GET /v1/handicap": "Course and playing handicap from handicap index, slope and course rating.",
            "GET /v1/stableford": "Stableford points for a hole from gross, par and strokes received."
        },
        "description": "Golf scoring maths: WHS course handicap, Stableford points and net score."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:08.618Z",
        "request_id": "07591e29-f2db-4dac-8a40-281a68a58c5b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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