# Paper Weight API
> Paper-weight maths as an API, computed locally and deterministically. The convert endpoint converts between grammage (GSM, grams per square metre — the universal measure) and the US basis weight in pounds, which depends on the paper stock type: bond/writing (basis 17×22 in), text/book/offset (25×38), cover (20×26), index (25.5×30.5), tag (24×36) and bristol (22.5×28.5). The weight endpoint computes the mass of a single sheet, a 500-sheet ream and the M-weight (the weight of 1000 sheets in pounds) at a given grammage and sheet size — accepting dimensions in millimetres, centimetres, inches or metres, or a named size (A3–A5, letter, legal, tabloid). The stocks endpoint is a reference of the US stock types with their conversion factors and basis sizes. Everything is computed locally and deterministically, so it is instant and private. Ideal for printing and publishing tools, stationery and packaging apps, print-shop estimators, and shipping-weight calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is paper grammage and basis weight; for general mass-unit conversion use a unit-conversion 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/paper-api/..."
```

## Pricing
- **Free** (Free) — 12,435 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 22,050 calls/Mo, 8 req/s
- **Pro** ($34/Mo) — 270,500 calls/Mo, 20 req/s
- **Mega** ($72/Mo) — 1,395,000 calls/Mo, 50 req/s

## Endpoints

### Paper

#### `GET /v1/convert` — GSM ↔ US basis weight

**Parameters:**
- `gsm` (query, optional, string) — Grammage (g/m²) Example: `80`
- `lb` (query, optional, string) — Or basis weight (lb) Example: `20`
- `stock` (query, optional, string) — bond|text|cover|index|tag|bristol Example: `bond`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paper-api/v1/convert?gsm=80&lb=20&stock=bond"
```

**Response:**
```json
{
    "data": {
        "gsm": 80,
        "note": "Basis weight is for bond stock (basis size 17×22 in, 500 sheets). gsm = lb × 3.7595.",
        "input": {
            "stock": "bond",
            "basis_size_in": "17×22"
        },
        "basis_weight_lb": 21.28,
        "factor_gsm_per_lb": 3.7595
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:13.573Z",
        "request_id": "0353c058-c609-4bc0-83f6-c5a7076f8a47"
    },
    "status": "ok",
    "message": "GSM <-> basis weight",
    "success": true
}
```

#### `GET /v1/stocks` — Paper stock reference

**Parameters:**
- `stock` (query, optional, string) — One stock, or omit for all Example: `cover`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paper-api/v1/stocks?stock=cover"
```

**Response:**
```json
{
    "data": {
        "note": "factor is gsm per pound of basis weight.",
        "basis": "20×26",
        "stock": "cover",
        "factor": 2.70489
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:13.671Z",
        "request_id": "086e1d6c-d679-483d-95ab-5988e83c338e"
    },
    "status": "ok",
    "message": "Stock reference",
    "success": true
}
```

#### `GET /v1/weight` — Sheet / ream / M-weight

**Parameters:**
- `gsm` (query, required, string) — Grammage Example: `80`
- `size` (query, optional, string) — a4|a3|letter|legal|… (or width+height) Example: `a4`
- `width` (query, optional, string) — Sheet width
- `height` (query, optional, string) — Sheet height
- `size_unit` (query, optional, string) — mm|cm|in|m Example: `mm`
- `count` (query, optional, string) — Number of sheets Example: `500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/paper-api/v1/weight?gsm=80&size=a4&size_unit=mm&count=500"
```

**Response:**
```json
{
    "data": {
        "note": "Sheet weight = gsm × sheet area (m²). Ream = 500 sheets; M-weight is the weight of 1000 sheets in pounds.",
        "input": {
            "gsm": 80,
            "count": 500,
            "area_m2": 0.06237
        },
        "total_kg": 2.4948,
        "m_weight_lb": 11.0002,
        "ream_500_kg": 2.4948,
        "sheet_grams": 4.9896,
        "total_grams": 2494.8,
        "ream_500_grams": 2494.8
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:13.760Z",
        "request_id": "3849415b-e9cc-42ed-b82e-c406269f3b4c"
    },
    "status": "ok",
    "message": "Sheet / ream weight",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "US basis weight depends on the stock's basis size; GSM (grammage) is universal. Named sizes A3–A5, letter, legal, tabloid are built in.",
        "stocks": [
            "bond",
            "text",
            "cover",
            "index",
            "tag",
            "bristol"
        ],
        "service": "paper",
        "endpoints": {
            "/v1/stocks": "Reference of US paper stock types, their factors and basis sizes.",
            "/v1/weight": "Weight of sheets, a 500-sheet ream and M-weight at a size and GSM.",
            "/v1/convert": "Convert between GSM and US basis weight (lb) for a paper stock type."
        },
        "description": "Paper-weight maths: grammage (GSM) ↔ US basis weight by stock type, and sheet/ream/M-weight at a size."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:13.858Z",
        "request_id": "9c6c30f8-f627-4846-b66b-daa3fdb314c2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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