# Color Distance API
> CIE colour science as an API: convert colours through the device-independent spaces and measure how different two colours really look. The convert endpoint takes a colour as hex, RGB or CIELAB and returns it in sRGB hex, RGB, CIE XYZ and CIELAB (D65 white point). The distance endpoint computes the perceptual difference between two colours with all three standard Delta-E formulas — CIE76 (plain Lab distance), CIE94, and CIEDE2000, the modern and most accurate metric — and tells you whether the difference is perceptible. The nearest endpoint finds the closest named colour to any colour by CIEDE2000. This is the maths behind colour matching, print and brand-colour QC, and tolerancing — distinct from simple hex/RGB/HSL conversion. Everything is computed locally and deterministically, so it is instant and private. Ideal for print and prepress, brand-colour compliance, textile and paint matching, image processing and computer vision, and design tooling. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is CIE colour difference; for hex/RGB/HSL/CMYK conversion, palettes and WCAG contrast use a colour 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/colordelta-api/..."
```

## Pricing
- **Free** (Free) — 6,935 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 16,450 calls/Mo, 8 req/s
- **Pro** ($28/Mo) — 215,500 calls/Mo, 20 req/s
- **Mega** ($66/Mo) — 1,120,000 calls/Mo, 50 req/s

## Endpoints

### Color

#### `GET /v1/convert` — Convert hex/RGB/Lab

**Parameters:**
- `hex` (query, optional, string) — A hex colour Example: `#ff0000`
- `rgb` (query, optional, string) — Or r,g,b
- `lab` (query, optional, string) — Or L,a,b

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/colordelta-api/v1/convert?hex=%23ff0000"
```

**Response:**
```json
{
    "data": {
        "hex": "#ff0000",
        "lab": [
            53.2408,
            80.0925,
            67.2032
        ],
        "rgb": [
            255,
            0,
            0
        ],
        "xyz": [
            41.2456,
            21.2673,
            1.93339
        ],
        "source": "hex"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:10.863Z",
        "request_id": "c7190da6-7886-4d24-994b-f525d845f935"
    },
    "status": "ok",
    "message": "Convert color",
    "success": true
}
```

#### `GET /v1/distance` — Delta-E between two colours

**Parameters:**
- `a_hex` (query, optional, string) — First colour Example: `#ff0000`
- `b_hex` (query, optional, string) — Second colour Example: `#ee0000`
- `a_lab` (query, optional, string) — Or first as L,a,b
- `b_lab` (query, optional, string) — Or second as L,a,b

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/colordelta-api/v1/distance?a_hex=%23ff0000&b_hex=%23ee0000"
```

**Response:**
```json
{
    "data": {
        "delta_e_76": 6.38049,
        "delta_e_94": 3.64434,
        "color_a_lab": [
            53.2408,
            80.0925,
            67.2032
        ],
        "color_b_lab": [
            49.7178,
            76.0173,
            63.7838
        ],
        "perceptible": "yes (>1 just-noticeable difference)",
        "delta_e_2000": 3.62598
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:10.968Z",
        "request_id": "91da3b12-51cc-4e26-8360-4893fe05a705"
    },
    "status": "ok",
    "message": "Color distance",
    "success": true
}
```

#### `GET /v1/nearest` — Nearest named colour

**Parameters:**
- `hex` (query, optional, string) — A colour Example: `#fe0102`
- `rgb` (query, optional, string) — Or r,g,b
- `lab` (query, optional, string) — Or L,a,b

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/colordelta-api/v1/nearest?hex=%23fe0102"
```

**Response:**
```json
{
    "data": {
        "lab": [
            53.0633,
            79.7986,
            66.5034
        ],
        "nearest_hex": "#ff0000",
        "delta_e_2000": 0.266671,
        "nearest_name": "red"
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:11.061Z",
        "request_id": "a31e04c3-af66-40f7-b7c9-babb095a36b3"
    },
    "status": "ok",
    "message": "Nearest named",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Color Distance API",
        "notes": "sRGB, D65 white point. CIEDE2000 implemented per Sharma et al. A Delta-E of ~1 is the just-noticeable difference. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/convert",
                "params": {
                    "hex": "a hex colour",
                    "lab": "or L,a,b",
                    "rgb": "or r,g,b"
                },
                "returns": "the colour in hex, RGB, XYZ and Lab"
            },
            {
                "path": "/v1/distance",
                "params": {
                    "a_hex": "first colour (or a_rgb / a_lab)",
                    "b_hex": "second colour (or b_rgb / b_lab)"
                },
                "returns": "Delta-E 76, 94 and 2000"
            },
            {
                "path": "/v1/nearest",
                "params": {
                    "hex": "a colour (or rgb / lab)"
                },
                "returns": "the nearest named colour by CIEDE2000"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "CIE colour science as an API: convert colours through the device-independent spaces and measure how different two colours really look. The convert endpoint takes a colour as hex, RGB or CIELAB and returns it in sRGB hex, RGB, CIE XYZ and CIE
…(truncated, see openapi.json for full schema)
```


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