# Size Conversion API
> International size conversion as an API, for the everyday wearables that ship in different scales around the world. The shoe endpoint converts a shoe size between EU (Paris point), UK, US men, US women, Mondopoint and foot length in centimetres — derived from the standard barleycorn and Paris-point relationships — and reports both the exact figure and the nearest standard half-size. The ring endpoint converts a ring size between US numeric, ISO 8653 (inside circumference in millimetres, used across most of Europe), inside diameter, inside circumference and the UK alphabetical scale. The hat endpoint converts a hat size between head circumference (centimetres or inches), the EU metric size, US and UK, with a simple S/M/L band. Everything is computed locally and deterministically, so it is instant and private. Ideal for fashion and footwear e-commerce, jewellery shops, size-guide widgets, returns-reduction tooling and international checkout. Pure local computation — no key, no third-party service, instant. Live, nothing stored. Guidance only — manufacturers' sizing varies, so always check the brand's own chart for a critical fit. 3 endpoints. This is wearable-size conversion; for plain length/weight 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/sizes-api/..."
```

## Pricing
- **Free** (Free) — 9,035 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 18,650 calls/Mo, 8 req/s
- **Pro** ($30/Mo) — 236,500 calls/Mo, 20 req/s
- **Mega** ($68/Mo) — 1,225,000 calls/Mo, 50 req/s

## Endpoints

### Sizes

#### `GET /v1/hat` — Convert a hat size

**Parameters:**
- `value` (query, required, string) — Head circumference or size Example: `57`
- `from` (query, required, string) — cm|in|us|uk Example: `cm`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sizes-api/v1/hat?value=57&from=cm"
```

**Response:**
```json
{
    "data": {
        "note": "US hat size = head circumference (inches) ÷ π in 1/8 steps; EU = head circumference in cm.",
        "input": {
            "from": "cm",
            "value": 57
        },
        "sizes": {
            "eu": 57,
            "uk": 7,
            "us": 7.125,
            "band": "M",
            "head_circumference_cm": 57,
            "head_circumference_in": 22.44
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.234Z",
        "request_id": "4b32f7bf-a80e-4461-87e8-e23286e7a288"
    },
    "status": "ok",
    "message": "Convert a hat size",
    "success": true
}
```

#### `GET /v1/ring` — Convert a ring size

**Parameters:**
- `value` (query, required, string) — Size, circumference, diameter or UK letter Example: `7`
- `from` (query, required, string) — us|iso|eu|circumference|diameter|uk Example: `us`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sizes-api/v1/ring?value=7&from=us"
```

**Response:**
```json
{
    "data": {
        "note": "US numeric uses ID = 11.63 + 0.8128·size mm; ISO/EU = inside circumference mm (ISO 8653). UK from standard chart.",
        "input": {
            "from": "us",
            "value": "7"
        },
        "sizes": {
            "uk": "N1/2",
            "us": 7,
            "iso_eu": 54.4,
            "us_rounded": 7,
            "inside_diameter_mm": 17.32,
            "inside_circumference_mm": 54.41
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.337Z",
        "request_id": "91156821-039f-4a1f-bf65-ed5c80ef3420"
    },
    "status": "ok",
    "message": "Convert a ring size",
    "success": true
}
```

#### `GET /v1/shoe` — Convert a shoe size

**Parameters:**
- `value` (query, required, string) — Size or foot length Example: `42`
- `from` (query, required, string) — eu|uk|us-men|us-women|mondopoint|cm Example: `eu`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sizes-api/v1/shoe?value=42&from=eu"
```

**Response:**
```json
{
    "data": {
        "note": "Guidance based on standard Mondopoint/Paris-point/barleycorn relationships; brands vary.",
        "input": {
            "from": "eu",
            "value": 42
        },
        "sizes": {
            "eu": 42,
            "uk": 8.3,
            "us_men": 9.3,
            "us_women": 10.8,
            "eu_rounded": 42,
            "mondopoint": 265,
            "uk_rounded": 8.5,
            "foot_length_cm": 26.5,
            "foot_length_mm": 265,
            "us_men_rounded": 9.5,
            "us_women_rounded": 11
        }
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.437Z",
        "request_id": "40001a2a-b978-4a5b-8dad-79e323efdb33"
    },
    "status": "ok",
    "message": "Convert a shoe size",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Guidance only — manufacturers' sizing varies; check the brand's own chart for a critical fit.",
        "service": "sizes",
        "systems": {
            "hat": [
                "cm",
                "in",
                "us",
                "uk"
            ],
            "ring": [
                "us",
                "iso",
                "eu",
                "circumference",
                "diameter",
                "uk"
            ],
            "shoe": [
                "eu",
                "uk",
                "us-men",
                "us-women",
                "mondopoint",
                "cm"
            ]
        },
        "endpoints": {
            "/v1/hat": "Convert a hat size between head circumference (cm/in), EU, US and UK.",
            "/v1/ring": "Convert a ring size between US numeric, ISO/EU circumference, diameter and UK letter.",
            "/v1/shoe": "Convert a shoe size between EU, UK, US (men/women), Mondopoint and foot length (cm)."
        },
        "description": "International size conversion for shoes, rings and hats, derived from standard ISO/Mondopoint/barleycorn relationships."
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:01.536Z",
        "request_id": "8e8f7d82-005e-40e4-a327-822cc91e23a4"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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