# Color Name API
> Name any colour. The nearest endpoint takes a colour as a hex, an rgb() value, an r,g,b triple or another name and returns the closest of the 140+ CSS named colours — matched perceptually with CIE76 Lab distance, not naive RGB, so the name actually looks right — along with the distance and whether it is an exact match. The name endpoint resolves a CSS colour keyword (e.g. rebeccapurple, cornflowerblue) to its hex and RGB, and list returns the whole named-colour set. Perfect for design tools and pickers, accessibility and theming, turning brand hex codes into human labels, and naming colours in generated palettes. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. Distinct from colour conversion / palette / contrast tooling, which does not name colours.

## 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/colorname-api/..."
```

## Pricing
- **Free** (Free) — 1,005 calls/Mo, 2 req/s
- **Starter** ($0/Mo) — 8,450 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 135,500 calls/Mo, 20 req/s
- **Mega** ($58/Mo) — 715,000 calls/Mo, 50 req/s

## Endpoints

### Color Name

#### `GET /v1/name` — Look up a colour name

**Parameters:**
- `name` (query, required, string) — A CSS colour name Example: `rebeccapurple`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/colorname-api/v1/name?name=rebeccapurple"
```

**Response:**
```json
{
    "data": {
        "hex": "#663399",
        "rgb": [
            102,
            51,
            153
        ],
        "name": "rebeccapurple"
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:43.540Z",
        "request_id": "68945c51-cb10-4796-a923-741207efce69"
    },
    "status": "ok",
    "message": "Look up a colour name",
    "success": true
}
```

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

**Parameters:**
- `color` (query, required, string) — hex, rgb(), r,g,b or a name Example: `#6597ed`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/colorname-api/v1/nearest?color=%236597ed"
```

**Response:**
```json
{
    "data": {
        "exact": false,
        "input": {
            "hex": "#6597ed",
            "rgb": [
                101,
                151,
                237
            ]
        },
        "nearest": {
            "hex": "#6495ed",
            "rgb": [
                100,
                149,
                237
            ],
            "name": "cornflowerblue"
        },
        "distance": 1.476
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:43.621Z",
        "request_id": "c6912607-23ff-479e-b125-4131202358e9"
    },
    "status": "ok",
    "message": "Nearest named colour",
    "success": true
}
```

### Reference

#### `GET /v1/list` — List named colours

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

**Response:**
```json
{
    "data": {
        "count": 148,
        "colors": [
            {
                "hex": "#f0f8ff",
                "rgb": [
                    240,
                    248,
                    255
                ],
                "name": "aliceblue"
            },
            {
                "hex": "#faebd7",
                "rgb": [
                    250,
                    235,
                    215
                ],
                "name": "antiquewhite"
            },
            {
                "hex": "#00ffff",
                "rgb": [
                    0,
                    255,
                    255
                ],
                "name": "aqua"
            },
            {
                "hex": "#7fffd4",
                "rgb": [
                    127,
                    255,
                    212
                ],
                "name": "aquamarine"
            },
            {
                "hex": "#f0ffff",
                "rgb": [
                    240,
                    255,
                    255
                ],
                "name": "azure"
            },
            {
                "hex": "#f5f5dc",
                "rgb": [
                    245,
                    245,
                    220
                ],
                "name": "beige"
            },
            {
                "hex": "#ffe4c4",
                "rgb": [
                    255,
                    228,
                    196
    
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Color Name API",
        "notes": "Uses the CSS Color Module Level 4 named-colour set. Distance is perceptual (Lab); 0 means an exact match. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/nearest",
                "params": {
                    "color": "hex, rgb(), r,g,b or a name (required)"
                },
                "returns": "the closest named colour, distance and whether it is exact"
            },
            {
                "path": "/v1/name",
                "params": {
                    "name": "a CSS colour name (required)"
                },
                "returns": "its hex and RGB"
            },
            {
                "path": "/v1/list",
                "params": [],
                "returns": "all named colours"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Find the nearest named CSS colour to any colour (perceptually, using CIE76 Lab distance), look up a CSS colour name to its hex/RGB, and list all 140+ named colours. Pure local, no key."
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:43.811Z",
        "request_id": "ad97512e-9463-409d-972e-b6b0a9390ac9"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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