# Percentage API
> Everyday percentage maths as an API. Four clear operations: what is X% of a value (15% of 200 = 30); what percentage one number is of another (30 is 15% of 200); the percentage change between two numbers, with the direction and the raw difference (200 → 250 is a 25% increase); and applying a percentage increase or decrease to a value (200 + 15% = 230). Handy for discounts, tips and tax, growth and KPI deltas, progress bars, dashboards and quick spreadsheet-style sums — without writing a formula. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. A focused calculator, distinct from a general math-expression engine.

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

## Pricing
- **Free** (Free) — 1,095 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 9,350 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 144,500 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 765,000 calls/Mo, 50 req/s

## Endpoints

### Percentage

#### `GET /v1/apply` — Apply an increase/decrease

**Parameters:**
- `value` (query, required, string) — The value Example: `200`
- `percent` (query, required, string) — The percentage Example: `15`
- `direction` (query, optional, string) — increase|decrease (default increase) Example: `increase`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/percentage-api/v1/apply?value=200&percent=15&direction=increase"
```

**Response:**
```json
{
    "data": {
        "delta": 30,
        "value": 200,
        "result": 230,
        "percent": 15,
        "direction": "increase"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:42.131Z",
        "request_id": "4bf29065-3d32-41fa-9820-cc8b52d2b720"
    },
    "status": "ok",
    "message": "Apply an increase/decrease",
    "success": true
}
```

#### `GET /v1/change` — Percentage change

**Parameters:**
- `from` (query, required, string) — Original value Example: `200`
- `to` (query, required, string) — New value Example: `250`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/percentage-api/v1/change?from=200&to=250"
```

**Response:**
```json
{
    "data": {
        "to": 250,
        "from": 200,
        "change": 25,
        "direction": "increase",
        "difference": 50
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:42.186Z",
        "request_id": "9ea795ae-fd60-46b1-8af2-14eabd4a2fe3"
    },
    "status": "ok",
    "message": "Percentage change",
    "success": true
}
```

#### `GET /v1/of` — X percent of a value

**Parameters:**
- `percent` (query, required, string) — The percentage Example: `15`
- `value` (query, required, string) — The value Example: `200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/percentage-api/v1/of?percent=15&value=200"
```

**Response:**
```json
{
    "data": {
        "value": 200,
        "result": 30,
        "percent": 15
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:42.254Z",
        "request_id": "b23d3ed9-9ec0-45be-a01a-f3a4ffb6d662"
    },
    "status": "ok",
    "message": "X percent of Y",
    "success": true
}
```

#### `GET /v1/what` — What percent X is of Y

**Parameters:**
- `part` (query, required, string) — The part Example: `30`
- `whole` (query, required, string) — The whole Example: `200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/percentage-api/v1/what?part=30&whole=200"
```

**Response:**
```json
{
    "data": {
        "part": 30,
        "whole": 200,
        "percent": 15
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:42.344Z",
        "request_id": "afeae27c-b51e-4c57-b06c-22a4c1345698"
    },
    "status": "ok",
    "message": "What percent is X of Y",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Percentage API",
        "notes": "Percentage change is relative to the magnitude of `from`. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/of",
                "params": {
                    "value": "required",
                    "percent": "required"
                },
                "returns": "percent% of value (15% of 200 = 30)"
            },
            {
                "path": "/v1/what",
                "params": {
                    "part": "required",
                    "whole": "required"
                },
                "returns": "what percent part is of whole"
            },
            {
                "path": "/v1/change",
                "params": {
                    "to": "required",
                    "from": "required"
                },
                "returns": "percentage change + direction"
            },
            {
                "path": "/v1/apply",
                "params": {
                    "value": "required",
                    "percent": "required",
                    "direction": "increase|decrease"
                },
                "returns": "the value after the change"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Everyday percentage maths: what is X% of Y, what percentage one numb
…(truncated, see openapi.json for full schema)
```


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