# Slope & Grade API
> Slope and grade maths as an API, computed locally and deterministically. The convert endpoint converts a slope between every common form — percent grade, angle in degrees, a ratio such as 1:12, per mille and rise-per-run — where the slope m = rise ÷ run = tan(angle). The distance endpoint relates the run (horizontal), the rise (vertical) and the slope distance (the hypotenuse) of a right-triangle slope: give any two, optionally with the grade or angle, and it returns the rest. The ramp endpoint sizes a wheelchair or ADA ramp — from a rise and a maximum slope (defaulting to 1:12, the ADA maximum of 8.33%) it returns the required run and total ramp length, and if you supply an actual run it checks whether the ramp is within the limit. Everything is computed locally and deterministically, so it is instant and private. Ideal for civil-engineering and surveying tools, road, trail and accessibility apps, construction and ramp design, and mapping software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is slope and grade geometry; for roof pitch specifically use a roofing 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/slope-api/..."
```

## Pricing
- **Free** (Free) — 12,235 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 21,850 calls/Mo, 8 req/s
- **Pro** ($34/Mo) — 268,500 calls/Mo, 20 req/s
- **Mega** ($72/Mo) — 1,385,000 calls/Mo, 50 req/s

## Endpoints

### Slope

#### `GET /v1/convert` — Convert percent / angle / ratio / per-mille

**Parameters:**
- `grade` (query, optional, string) — Grade % Example: `10`
- `angle` (query, optional, string) — Or angle (degrees)
- `ratio` (query, optional, string) — Or ratio (1:12)
- `per_mille` (query, optional, string) — Or per mille

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/slope-api/v1/convert?grade=10"
```

**Response:**
```json
{
    "data": {
        "note": "Slope m = rise ÷ run = tan(angle). Grade % = m × 100; ratio is 1:(run per unit rise).",
        "input": [],
        "ratio": "1:10",
        "per_mille": 100,
        "rise_per_run": 0.1,
        "angle_degrees": 5.7106,
        "grade_percent": 10
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:14.361Z",
        "request_id": "1f407d65-909e-4305-bce3-d823600be5fb"
    },
    "status": "ok",
    "message": "Slope conversion",
    "success": true
}
```

#### `GET /v1/distance` — Run / rise / slope distance

**Parameters:**
- `run` (query, optional, string) — Horizontal run Example: `100`
- `rise` (query, optional, string) — Vertical rise Example: `10`
- `slope_distance` (query, optional, string) — Slope distance (hypotenuse)
- `grade` (query, optional, string) — Or grade %
- `angle` (query, optional, string) — Or angle (degrees)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/slope-api/v1/distance?run=100&rise=10"
```

**Response:**
```json
{
    "data": {
        "run": 100,
        "note": "Right-triangle relations: slope distance = √(run² + rise²); grade = rise ÷ run.",
        "rise": 10,
        "input": [],
        "ratio": "1:10",
        "per_mille": 100,
        "rise_per_run": 0.1,
        "angle_degrees": 5.7106,
        "grade_percent": 10,
        "slope_distance": 100.4988
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:14.459Z",
        "request_id": "daf08ee3-365e-469d-89e6-fe12a0495db5"
    },
    "status": "ok",
    "message": "Run / rise / slope distance",
    "success": true
}
```

#### `GET /v1/ramp` — Wheelchair / ADA ramp

**Parameters:**
- `rise` (query, required, string) — Vertical rise Example: `30`
- `max_slope` (query, optional, string) — Max ratio (default 1:12) Example: `1:12`
- `max_grade` (query, optional, string) — Or max grade %
- `run` (query, optional, string) — Actual run (to check compliance)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/slope-api/v1/ramp?rise=30&max_slope=1%3A12"
```

**Response:**
```json
{
    "data": {
        "note": "ADA default is 1:12 (max 8.33% grade). Required run = rise × ratio. Provide run to check an existing ramp.",
        "input": {
            "rise": 30,
            "max_slope_ratio": "1:12",
            "max_grade_percent": 8.333
        },
        "ramp_length": 361.248,
        "required_run": 360,
        "angle_degrees": 4.764
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:14.529Z",
        "request_id": "ff4c162f-35a6-40af-a6c5-641327922b7d"
    },
    "status": "ok",
    "message": "Ramp calculation",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Slope m = rise ÷ run = tan(angle). ADA ramp default is 1:12 (≤ 8.33% grade).",
        "service": "slope",
        "endpoints": {
            "/v1/ramp": "Wheelchair/ADA ramp: required run and length for a rise (default 1:12), and compliance check.",
            "/v1/convert": "Convert a slope between grade %, angle, ratio (1:12) and per mille.",
            "/v1/distance": "Relate run, rise and slope distance from any two (plus grade/angle)."
        },
        "description": "Slope/grade maths: convert percent/angle/ratio/per-mille, relate run/rise/slope distance, and check a ramp."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:14.619Z",
        "request_id": "51a806b2-27dc-4c36-82cd-b3b95ecfba05"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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