# Dimensional Weight API
> Shipping dimensional-weight maths as an API. Carriers bill the greater of a parcel's actual weight and its dimensional (volumetric) weight — the volume divided by a carrier "dim divisor" — so a big, light box can cost far more than the scales suggest. The dimweight endpoint computes the dimensional weight in both pounds and kilograms from the length, width and height (in inches or centimetres) and a dim divisor, which you can give directly or pick by carrier (UPS, FedEx, USPS, DHL, IATA). The billable endpoint takes the actual weight as well and returns the billable weight — the greater of actual and dimensional — telling you which one you will be charged on. The girth endpoint computes the girth (twice the width plus height of the two smaller sides), the length-plus-girth and the longest side, and flags whether the parcel is oversize against length limits (defaulting to typical US ground values). Everything is computed locally and deterministically, so it is instant and private. Ideal for e-commerce checkout and shipping estimators, fulfilment and warehouse tools, freight and logistics software, and packaging optimisation. Pure local computation — no key, no third-party service, instant. Live, nothing stored. Divisors and limits are typical published values — confirm with your carrier and service. 3 endpoints. This is dimensional-weight maths; for live shipping rates use a carrier's own API, and for plain 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/dimweight-api/..."
```

## Pricing
- **Free** (Free) — 9,435 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 19,050 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 240,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,245,000 calls/Mo, 50 req/s

## Endpoints

### Shipping

#### `GET /v1/billable` — Billable weight (greater of actual & dim)

**Parameters:**
- `length` (query, required, string) — Length Example: `12`
- `width` (query, required, string) — Width Example: `12`
- `height` (query, required, string) — Height Example: `12`
- `actual_weight` (query, required, string) — Actual weight Example: `8`
- `unit` (query, optional, string) — in|cm Example: `in`
- `weight_unit` (query, optional, string) — lb|kg Example: `lb`
- `carrier` (query, optional, string) — Carrier preset

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dimweight-api/v1/billable?length=12&width=12&height=12&actual_weight=8&unit=in&weight_unit=lb"
```

**Response:**
```json
{
    "data": {
        "note": "Billable weight is the greater of actual and dimensional weight. Carriers usually round up to the next lb or 0.5 kg.",
        "input": {
            "unit": "in",
            "width": 12,
            "height": 12,
            "length": 12,
            "carrier": null,
            "divisor": 139,
            "weight_unit": "lb",
            "actual_weight": 8
        },
        "charged_on": "dimensional",
        "actual_weight_kg": 3.63,
        "actual_weight_lb": 8,
        "billable_weight_kg": 5.64,
        "billable_weight_lb": 12.43,
        "dimensional_weight_kg": 5.64,
        "dimensional_weight_lb": 12.43
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.304Z",
        "request_id": "31316f43-4f2c-41ab-85a8-a0abd0da915b"
    },
    "status": "ok",
    "message": "Billable weight",
    "success": true
}
```

#### `GET /v1/dimweight` — Dimensional (volumetric) weight

**Parameters:**
- `length` (query, required, string) — Length Example: `12`
- `width` (query, required, string) — Width Example: `12`
- `height` (query, required, string) — Height Example: `12`
- `unit` (query, optional, string) — in|cm (default in) Example: `in`
- `carrier` (query, optional, string) — ups|fedex|usps|dhl|iata
- `divisor` (query, optional, string) — Or explicit dim divisor

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dimweight-api/v1/dimweight?length=12&width=12&height=12&unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "Dimensional weight = volume ÷ dim divisor (in³/lb for imperial, cm³/kg for metric). Carriers usually round up.",
        "input": {
            "unit": "in",
            "width": 12,
            "height": 12,
            "length": 12,
            "carrier": null,
            "divisor": 139
        },
        "volume": 1728,
        "volume_unit": "in3",
        "divisor_source": "default",
        "dimensional_weight_kg": 5.64,
        "dimensional_weight_lb": 12.43
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.412Z",
        "request_id": "7a66c9b0-592d-4c6d-ae0d-5f07e07a5beb"
    },
    "status": "ok",
    "message": "Dimensional weight",
    "success": true
}
```

#### `GET /v1/girth` — Girth & oversize check

**Parameters:**
- `length` (query, required, string) — Length Example: `40`
- `width` (query, required, string) — Width Example: `20`
- `height` (query, required, string) — Height Example: `20`
- `unit` (query, optional, string) — in|cm Example: `in`
- `max_length` (query, optional, string) — Length limit
- `max_length_girth` (query, optional, string) — Length+girth limit

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dimweight-api/v1/girth?length=40&width=20&height=20&unit=in"
```

**Response:**
```json
{
    "data": {
        "note": "Girth = 2 × (width + height) of the two smaller sides. Default limits are typical US ground values (UPS/FedEx).",
        "girth": 80,
        "input": {
            "unit": "in",
            "width": 20,
            "height": 20,
            "length": 40
        },
        "limits": {
            "unit": "in",
            "max_length": 108,
            "max_length_girth": 165
        },
        "oversize": false,
        "longest_side": 40,
        "oversize_reasons": [],
        "length_plus_girth": 120
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.510Z",
        "request_id": "f78f7c9e-fc59-4259-aa6a-4920cc67c6d3"
    },
    "status": "ok",
    "message": "Girth & oversize",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Divisors and limits are typical published values — confirm with your carrier and service.",
        "service": "dimweight",
        "carriers": [
            "ups",
            "fedex",
            "usps",
            "dhl",
            "iata",
            "intl"
        ],
        "defaults": {
            "metric_divisor_cm3_per_kg": 5000,
            "imperial_divisor_in3_per_lb": 139
        },
        "endpoints": {
            "/v1/girth": "Girth, length+girth and oversize check against length limits.",
            "/v1/billable": "Billable weight = greater of actual and dimensional weight.",
            "/v1/dimweight": "Dimensional (volumetric) weight from L×W×H and a dim divisor or carrier."
        },
        "description": "Dimensional/volumetric weight and shipping-size maths: dim weight, billable weight and girth/oversize checks."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:59.609Z",
        "request_id": "61e96469-eb1f-4c4e-8274-2fa3f359d9ea"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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