# Roof Pitch API
> Roofing geometry as an API, computed locally and deterministically. The pitch endpoint converts freely between the three ways trades describe a roof slope — the pitch as rise per 12 of run (the X:12 notation), the angle in degrees and the slope as a percentage — using angle = atan(pitch/12); a 6:12 roof is 26.57° and a 50 % slope, and it also returns the pitch multiplier √(1 + tan²) that scales a flat plan length to the true along-slope length. The rafter endpoint computes the common rafter length from the horizontal run and the pitch, rafter = √(run² + rise²) with rise = run·tan(angle), and adds the along-slope length of an optional horizontal overhang — a 12-unit run at 6:12 needs a 13.42-unit rafter. The area endpoint converts a flat building footprint into the actual sloped roof surface area, footprint / cos(angle), the figure you need to order shingles, membrane or underlay; a 100 m² footprint under a 6:12 roof is about 111.8 m². Lengths are unit-agnostic — use a consistent unit. Everything is computed locally and deterministically, so it is instant and private. Ideal for roofing, construction, contractor-estimating, home-improvement, solar-install and architecture app developers, take-off and material-ordering tools, and trade software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is roofing-specific geometry; for a general grade or gradient use a slope 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/roofpitch-api/..."
```

## Pricing
- **Free** (Free) — 5,800 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 58,000 calls/Mo, 6 req/s
- **Pro** ($13/Mo) — 255,000 calls/Mo, 15 req/s
- **Mega** ($41/Mo) — 1,450,000 calls/Mo, 40 req/s

## Endpoints

### Roof

#### `GET /v1/area` — Sloped roof area

**Parameters:**
- `footprint_area` (query, required, string) — Flat footprint area Example: `100`
- `pitch` (query, optional, string) — Pitch (X:12) Example: `6`
- `angle` (query, optional, string) — Or angle (deg)
- `slope_percent` (query, optional, string) — Or slope (%)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roofpitch-api/v1/area?footprint_area=100&pitch=6"
```

**Response:**
```json
{
    "data": {
        "note": "Sloped roof area = footprint / cos(angle). The footprint is the flat plan area covered by the roof; multiply by the pitch multiplier to get the true surface area for materials.",
        "inputs": {
            "angle_deg": 26.565051,
            "footprint_area": 100
        },
        "roof_area": 111.803399,
        "pitch_multiplier": 1.11803399
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:23.277Z",
        "request_id": "9891adef-94b4-4bda-a30b-1d26f78e7ac6"
    },
    "status": "ok",
    "message": "Roof area",
    "success": true
}
```

#### `GET /v1/pitch` — Pitch / angle / slope

**Parameters:**
- `pitch` (query, optional, string) — Rise per 12 of run (X:12) Example: `6`
- `angle` (query, optional, string) — Roof angle (degrees)
- `slope_percent` (query, optional, string) — Slope (%)
- `rise` (query, optional, string) — Rise
- `run` (query, optional, string) — Run

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roofpitch-api/v1/pitch?pitch=6"
```

**Response:**
```json
{
    "data": {
        "note": "Roof pitch as the rise per 12 of run (X:12), the angle and the slope %. angle = atan(pitch/12). The pitch multiplier √(1+tan²) scales plan length to along-slope length.",
        "inputs": {
            "pitch": 6
        },
        "angle_deg": 26.565051,
        "pitch_label": "6:12",
        "pitch_x_in_12": 6,
        "slope_percent": 50,
        "pitch_multiplier": 1.11803399
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:23.388Z",
        "request_id": "347fd5c1-7d80-4413-8a83-42ed1133199c"
    },
    "status": "ok",
    "message": "Roof pitch conversion",
    "success": true
}
```

#### `GET /v1/rafter` — Common rafter length

**Parameters:**
- `run` (query, required, string) — Horizontal run Example: `12`
- `pitch` (query, optional, string) — Pitch (X:12) Example: `6`
- `angle` (query, optional, string) — Or angle (deg)
- `rise` (query, optional, string) — Or rise
- `overhang` (query, optional, string) — Horizontal overhang

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/roofpitch-api/v1/rafter?run=12&pitch=6"
```

**Response:**
```json
{
    "data": {
        "note": "Common rafter = √(run² + rise²), with rise = run·tan(angle). The overhang is measured horizontally and extended along the slope. Use the same length unit for run and overhang.",
        "rise": 6,
        "inputs": {
            "run": 12,
            "angle_deg": 26.565051
        },
        "rafter_length": 13.416408,
        "overhang_length": 0,
        "total_rafter_length": 13.416408
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:23.499Z",
        "request_id": "69b92462-f159-42d0-96af-ba5c8a5b2e12"
    },
    "status": "ok",
    "message": "Rafter length",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Pitch is the rise per 12 units of run (X:12). Lengths are unit-agnostic — use a consistent unit. Roofing-specific geometry; for a general grade/gradient use a slope API.",
        "service": "roofpitch-api",
        "endpoints": {
            "GET /v1/area": "Actual sloped roof area from the footprint and pitch.",
            "GET /v1/meta": "This document.",
            "GET /v1/pitch": "Convert between roof pitch (X:12), angle and slope percent.",
            "GET /v1/rafter": "Common rafter length from run and pitch, with overhang."
        },
        "description": "Roofing geometry: roof pitch (X:12) ↔ angle ↔ slope, common rafter length, and sloped roof area from the footprint."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:23.604Z",
        "request_id": "16337190-e830-46ee-9bd9-e714cd76afaa"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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