# Fret Spacing API
> Fretted-instrument lutherie maths as an API, computed locally and deterministically — the fret positions a guitar, bass, mandolin or ukulele builder slots a fingerboard to. This is instrument-building geometry, not music theory. The positions endpoint lays out a whole fingerboard from the scale length using the twelve-tone equal-temperament rule: the distance from the nut to fret n = scale length × (1 − 1 ÷ 2^(n/12)), so the 12th fret lands at exactly half the scale (the octave) and each gap shrinks by the constant ratio 2^(1/12) ≈ 1.0595 toward the bridge — a 25.5-inch Fender scale puts fret 1 at 1.431 inches and fret 12 at 12.75. The fret endpoint gives one fret’s distance from the nut, from the previous fret and to the bridge; the scalelength endpoint runs it backwards, recovering the scale length from a measured distance to a known fret (measure to the 12th and double it). It works in inches or millimetres — 25.5 Fender, 24.75 Gibson, 25.4 classical, 34 bass. Everything is computed locally and deterministically, so it is instant and private. Ideal for lutherie, guitar-building, instrument-design and maker app developers, fingerboard-slotting and fret-calculator tools, and CAD/CNC templates. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For note names or frequencies use a music-theory 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/fretspacing-api/..."
```

## Pricing
- **Free** (Free) — 6,580 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 56,900 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 234,800 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,349,000 calls/Mo, 40 req/s

## Endpoints

### Fret

#### `GET /v1/fret` — Single fret position

**Parameters:**
- `scale_length` (query, required, string) — Scale length Example: `25.5`
- `fret` (query, required, string) — Fret number Example: `12`
- `unit` (query, optional, string) — in or mm Example: `in`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fretspacing-api/v1/fret?scale_length=25.5&fret=12&unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "From the nut to fret n = scale × (1 − 1/2^(n/12)). The spacing shrinks geometrically toward the bridge — each fret is the same ratio (2^(1/12) ≈ 1.0595) closer than the last.",
        "inputs": {
            "fret": 12,
            "unit": "in",
            "scale_length": 25.5
        },
        "from_nut": 12.75,
        "from_previous_fret": 0.7582,
        "remaining_to_bridge": 12.75
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:56.847Z",
        "request_id": "a749f37a-4648-4113-b56c-a4b15b94aac6"
    },
    "status": "ok",
    "message": "Single fret",
    "success": true
}
```

#### `GET /v1/positions` — All fret positions

**Parameters:**
- `scale_length` (query, required, string) — Scale length Example: `25.5`
- `frets` (query, optional, string) — Number of frets (default 22) Example: `22`
- `unit` (query, optional, string) — in or mm (default in) Example: `in`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fretspacing-api/v1/positions?scale_length=25.5&frets=22&unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "Distance from the nut to fret n = scale length × (1 − 1 ÷ 2^(n/12)), equal temperament. The 12th fret lands at exactly half the scale (the octave). Measure to the centre of each fret slot from the nut, not fret-to-fret cumulatively.",
        "frets": [
            {
                "fret": 1,
                "from_nut": 1.4312,
                "from_previous": 1.4312
            },
            {
                "fret": 2,
                "from_nut": 2.7821,
                "from_previous": 1.3509
            },
            {
                "fret": 3,
                "from_nut": 4.0571,
                "from_previous": 1.2751
            },
            {
                "fret": 4,
                "from_nut": 5.2606,
                "from_previous": 1.2035
            },
            {
                "fret": 5,
                "from_nut": 6.3966,
                "from_previous": 1.1359
            },
            {
                "fret": 6,
                "from_nut": 7.4688,
                "from_previous": 1.0722
            },
            {
                "fret": 7,
                "from_nut": 8.4808,
                "from_previous": 1.012
            },
            {
                "fret": 8,
                "from_nut": 9.436,
                "from_previous": 0.9552
            },
            {
                "fret": 9,
                "from_nut": 10.3376,
                "from_previous": 0.9016
            },
            {
        
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/scalelength` — Scale length from a fret

**Parameters:**
- `distance_from_nut` (query, required, string) — Measured distance from nut Example: `12.75`
- `fret` (query, required, string) — Fret number measured to Example: `12`
- `unit` (query, optional, string) — in or mm Example: `in`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fretspacing-api/v1/scalelength?distance_from_nut=12.75&fret=12&unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "Scale length = distance ÷ (1 − 1/2^(fret/12)). Measuring to the 12th fret is easiest: the scale length is just twice that distance. Common scales: 25.5\" (Fender), 24.75\" (Gibson), 25.4\" classical, 34\" bass.",
        "inputs": {
            "fret": 12,
            "unit": "in",
            "distance_from_nut": 12.75
        },
        "scale_length": 25.5
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:57.039Z",
        "request_id": "0e1d56ea-3ef2-40b1-a242-32a2b82d450e"
    },
    "status": "ok",
    "message": "Scale length",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Equal temperament: distance to fret n = scale × (1 − 1/2^(n/12)); 12th fret = half the scale. Inches or millimetres. For note names, frequencies or chords use a music-theory API.",
        "service": "fretspacing-api",
        "endpoints": {
            "GET /v1/fret": "Position of one fret (from the nut and from the previous fret).",
            "GET /v1/meta": "This document.",
            "GET /v1/positions": "All fret positions from the nut for a scale length.",
            "GET /v1/scalelength": "Scale length back-calculated from a measured distance to a fret."
        },
        "description": "Fretted-instrument lutherie maths: fret positions from a scale length, a single fret's position, and the scale length from a measured fret."
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:57.146Z",
        "request_id": "3ca00617-70f1-46cc-9e9d-3d59ec960706"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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