# Unit Price API
> Unit-price and best-value maths as an API — the supermarket "which is cheaper" calculation, computed locally and deterministically and entirely currency-agnostic. The unit endpoint normalises a pack price to a price per standard unit: from a price, a pack size and its unit (and an optional multipack count) it returns the price per kilogram, per 100 g and per pound for weight; per litre, per 100 ml and per fluid ounce for volume; or per item for counted goods — plus the price per pack item for multipacks. The compare endpoint takes several pack options as a simple list (such as "3@500g,5@1kg,4.5@750g"), ranks them cheapest-per-unit first, names the best value and reports the percentage saving versus the most expensive. The convert endpoint turns a unit price given in one basis (for example per pound) into the other bases for its measure. Everything is computed locally and deterministically, so it is instant and private. Options being compared must share a measure (all weight, all volume or all count). Ideal for shopping and grocery apps, price-comparison and deal sites, budgeting tools, and retail and procurement software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is unit-price comparison; for profit margin and markup use a margin 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/unitprice-api/..."
```

## Pricing
- **Free** (Free) — 10,735 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 20,350 calls/Mo, 8 req/s
- **Pro** ($32/Mo) — 253,500 calls/Mo, 20 req/s
- **Mega** ($70/Mo) — 1,310,000 calls/Mo, 50 req/s

## Endpoints

### Price

#### `GET /v1/compare` — Compare options, find best value

**Parameters:**
- `options` (query, required, string) — price@size[unit] list Example: `3@500g,5@1kg,4.5@750g`
- `unit` (query, optional, string) — Shared unit if options omit it

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitprice-api/v1/compare?options=3%40500g%2C5%401kg%2C4.5%40750g"
```

**Response:**
```json
{
    "data": {
        "note": "Options ranked cheapest-per-unit first. savings_vs_worst_percent compares the best option to the most expensive per unit.",
        "measure": "weight",
        "options": [
            {
                "rank": 1,
                "size": 1,
                "unit": "kg",
                "count": 1,
                "label": "5@1kg",
                "price": 5,
                "is_best": true,
                "unit_price": {
                    "per_g": 0.005,
                    "per_kg": 5,
                    "per_lb": 2.268,
                    "per_100g": 0.5
                }
            },
            {
                "rank": 2,
                "size": 500,
                "unit": "g",
                "count": 1,
                "label": "3@500g",
                "price": 3,
                "is_best": false,
                "unit_price": {
                    "per_g": 0.006,
                    "per_kg": 6,
                    "per_lb": 2.7216,
                    "per_100g": 0.6
                }
            },
            {
                "rank": 3,
                "size": 750,
                "unit": "g",
                "count": 1,
                "label": "4.5@750g",
                "price": 4.5,
                "is_best": false,
                "unit_price": {
                    "per_g": 0.006,
                    "per_kg": 6,
                    "per_lb": 2.7216,
                    "per_100g": 0.6
                }
            
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/convert` — Convert a unit price between bases

**Parameters:**
- `price` (query, required, string) — Price per one unit Example: `5`
- `from` (query, required, string) — Unit it is per (e.g. lb) Example: `lb`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitprice-api/v1/convert?price=5&from=lb"
```

**Response:**
```json
{
    "data": {
        "note": "Converts a price expressed per one unit into the standard per-unit bases for that measure.",
        "input": {
            "from": "lb",
            "price": 5,
            "measure": "weight"
        },
        "unit_price": {
            "per_g": 0.011023,
            "per_kg": 11.0231,
            "per_lb": 5,
            "per_100g": 1.1023
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.206Z",
        "request_id": "a7d48585-f00b-4471-abeb-5fcc4d7e274f"
    },
    "status": "ok",
    "message": "Convert unit price",
    "success": true
}
```

#### `GET /v1/unit` — Price per standard unit

**Parameters:**
- `price` (query, required, string) — Pack price Example: `3`
- `size` (query, required, string) — Pack size Example: `500`
- `unit` (query, required, string) — g|kg|oz|lb|ml|l|floz|each Example: `g`
- `count` (query, optional, string) — Multipack count Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/unitprice-api/v1/unit?price=3&size=500&unit=g&count=1"
```

**Response:**
```json
{
    "data": {
        "note": "Unit price = pack price ÷ total quantity. Multipacks multiply size by count.",
        "input": {
            "size": 500,
            "unit": "g",
            "count": 1,
            "price": 3,
            "measure": "weight"
        },
        "unit_price": {
            "per_g": 0.006,
            "per_kg": 6,
            "per_lb": 2.7216,
            "per_100g": 0.6
        },
        "total_base_quantity": 500
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.297Z",
        "request_id": "6074fb9e-00fd-414f-9825-f0c8cb1abb64"
    },
    "status": "ok",
    "message": "Unit price",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Currency-agnostic. Compare options must share a measure (all weight, all volume or all count).",
        "units": {
            "count": [
                "each",
                "item",
                "pack"
            ],
            "volume": [
                "ml",
                "cl",
                "l",
                "floz",
                "pt",
                "qt",
                "gal",
                "cup"
            ],
            "weight": [
                "mg",
                "g",
                "kg",
                "oz",
                "lb"
            ]
        },
        "service": "unitprice",
        "endpoints": {
            "/v1/unit": "Price per kg/litre/100g/item from a pack price, size and unit (with multipack count).",
            "/v1/compare": "Rank several pack options by price per unit and report the saving vs the worst.",
            "/v1/convert": "Convert a unit price (e.g. per lb) into the other bases for its measure."
        },
        "description": "Unit-price and best-value maths: normalise pack prices, compare options, and convert a unit price between bases."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:20.372Z",
        "request_id": "0dbb05cd-ce95-494e-9e0c-03d6ef4d8f9d"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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