# Aspect Ratio API
> Aspect-ratio and resize maths on plain dimensions — no image upload needed. The ratio endpoint reduces a width×height to its simplest integer ratio (1920×1080 → 16:9), its decimal value and a common name. The resize endpoint scales a dimension while preserving the ratio: give a new width or a new height and get the other side. The fit endpoint fits a source size into a target box using contain (letterbox) or cover (crop), returning the resulting size, the scale factor and the centering offset. Perfect for responsive layouts and CSS aspect-ratio, video and thumbnail framing, image-grid planning and print sizing. Pure local computation — it works on numbers only and never touches image files. Live, nothing stored. 4 endpoints. Distinct from image processing/resizing (which operates on actual files) and from geometry of shapes.

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

## Pricing
- **Free** (Free) — 840 calls/Mo, 2 req/s
- **Starter** ($2/Mo) — 6,900 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 129,000 calls/Mo, 20 req/s
- **Mega** ($56/Mo) — 665,000 calls/Mo, 50 req/s

## Endpoints

### Aspect Ratio

#### `GET /v1/fit` — Fit dimensions into a box

**Parameters:**
- `width` (query, required, string) — Source width Example: `1920`
- `height` (query, required, string) — Source height Example: `1080`
- `box_width` (query, required, string) — Box width Example: `800`
- `box_height` (query, required, string) — Box height Example: `800`
- `mode` (query, optional, string) — contain|cover (default contain) Example: `contain`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aspectratio-api/v1/fit?width=1920&height=1080&box_width=800&box_height=800&mode=contain"
```

**Response:**
```json
{
    "data": {
        "box": {
            "width": 800,
            "height": 800
        },
        "mode": "contain",
        "scale": 0.416667,
        "width": 800,
        "height": 450,
        "offset": {
            "x": 0,
            "y": 175
        },
        "source": {
            "width": 1920,
            "height": 1080
        }
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:44.710Z",
        "request_id": "fbaff8f9-eb21-43dc-9760-530cbd003b19"
    },
    "status": "ok",
    "message": "Fit into a box",
    "success": true
}
```

#### `GET /v1/ratio` — Simplify an aspect ratio

**Parameters:**
- `width` (query, required, string) — Width Example: `1920`
- `height` (query, required, string) — Height Example: `1080`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aspectratio-api/v1/ratio?width=1920&height=1080"
```

**Response:**
```json
{
    "data": {
        "ratio": "16:9",
        "width": 1920,
        "height": 1080,
        "decimal": 1.777778,
        "common_name": "Widescreen HD (16:9)"
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:44.802Z",
        "request_id": "b8ff6cb3-9add-48b4-bc8b-4bddab54052c"
    },
    "status": "ok",
    "message": "Simplify an aspect ratio",
    "success": true
}
```

#### `GET /v1/resize` — Resize keeping the ratio

**Parameters:**
- `width` (query, required, string) — Original width Example: `1920`
- `height` (query, required, string) — Original height Example: `1080`
- `new_width` (query, optional, string) — Target width (or set new_height) Example: `1280`
- `new_height` (query, optional, string) — Target height (or set new_width)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aspectratio-api/v1/resize?width=1920&height=1080&new_width=1280"
```

**Response:**
```json
{
    "data": {
        "from": {
            "width": 1920,
            "height": 1080
        },
        "scale": 0.666667,
        "width": 1280,
        "height": 720
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:44.902Z",
        "request_id": "364f7fa4-b010-4be7-8ec7-7ccbaee5dc4f"
    },
    "status": "ok",
    "message": "Resize keeping ratio",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Aspect Ratio API",
        "notes": "Operates on numbers only — for layout, video frames, thumbnails and responsive planning. It does not process image files.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/ratio",
                "params": {
                    "width": "required",
                    "height": "required"
                },
                "returns": "simplified ratio (e.g. 16:9), decimal, common name"
            },
            {
                "path": "/v1/resize",
                "params": {
                    "width": "required",
                    "height": "required",
                    "new_width": "or",
                    "new_height": "one of these"
                },
                "returns": "the other dimension, keeping the ratio"
            },
            {
                "path": "/v1/fit",
                "params": {
                    "mode": "contain|cover",
                    "width": "required",
                    "height": "required",
                    "box_width": "required",
                    "box_height": "required"
                },
                "returns": "fitted width/height, scale and centering offset"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Aspect-ratio and resize maths on plain dimensions 
…(truncated, see openapi.json for full schema)
```


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