---
name: z87:colors
description: Unified paint color database: ~30K colors across 20+ brands with cross-brand matching via CIEDE2000 perceptual distance, color harmony generation, coordinating color strips, and palette suggestions.
---

Anonymous: 600 tok/min. Key: `GET https://z87.ai/api/use` → `X-Api-Key` header, 6000 tok/min. On `429`, wait 1s.

## Finding colors

Search by field: /search?q=name:navy brand:benjamin-moore family:blue
Filter by undertone: /search?q=brand:benjamin-moore family:white undertone:warm
Filter by LRV: /search?q=brand:behr family:blue&lrv_min=50&lrv_max=70
Filter by lightness: /search?q=brand:sherwin-williams&lightness_min=60&lightness_max=80
Browse collections: /search?q=brand:benjamin-moore collection:historical
Autocomplete: /suggest?q=hale
Full detail: /colors/{id}

## Cross-brand matching

Find closest real paint to any hex: /nearest?hex=546670&brand=benjamin-moore
Find equivalent in another brand: /similar/{id}?brand=behr

## Color harmonies

/harmonies/{id} — complementary, analogous, triadic, split-complementary, tetradic schemes resolved to real paints
/strip/{id} — monochromatic coordinating colors from the same paint strip (mainly Sherwin-Williams)
/palette/{id} — wall/trim/accent/ceiling palette from one color

## Brands

Paint: sherwin-williams, benjamin-moore, behr, ppg, valspar, farrow-ball, dunn-edwards, kilz, colorhouse, dutch
Industrial: ral, avery, hks, toyo, trumatch, vista, neenah, mpc, kobra, dic, ikea, hl

All endpoints accept both **GET with query parameters** and **POST with JSON body**.

## Endpoints

### `https://z87.ai/api/colors/search`

Field-qualified search with numeric filters. Fields: name, brand, family, code, undertone (warm/cool/neutral), collection. Numeric: lrv_min/lrv_max (0-100), lightness_min/lightness_max (0-100). Example: brand:benjamin-moore family:white undertone:warm

| Param | Type | Required | Default |
|-------|------|----------|---------|
| q | string | no | — |
| lrv_min | f32 | no | — |
| lrv_max | f32 | no | — |
| lightness_min | f32 | no | — |
| lightness_max | f32 | no | — |
| limit | u32 | no | 20 |
| offset | u32 | no | 0 |

**Example:** `GET https://z87.ai/api/colors/search?q=brand:benjamin-moore+family:white+undertone:warm&lrv_min=80&limit=1`

**Response:**
```json
{
  "colors": [
    {
      "id": 5039,
      "name": "Gardenia",
      "brand": "benjamin-moore",
      "code": "AF-10",
      "hex": "F4F1EA",
      "rgb": [244, "...2 more"],
      "lrv": 88.08000183105469,
      "family": "white"
    }
  ],
  "total": 160,
  "limit": 1,
  "offset": 0
}
```

### `https://z87.ai/api/colors/nearest`

Find closest colors to a hex value by CIEDE2000 perceptual distance. Filter by brand, family.

| Param | Type | Required | Default |
|-------|------|----------|---------|
| hex | string | **yes** | — |
| brand | string | no | — |
| is_paint | bool | no | — |
| family | string | no | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/colors/nearest?hex=546670&brand=benjamin-moore&limit=1`

**Response:**
```json
{
  "query_hex": "546670",
  "results": [
    {
      "color": {
        "id": 6882,
        "name": "Spellbound",
        "brand": "benjamin-moore",
        "code": "1659",
        "hex": "4F6570",
        "rgb": "...",
        "hsl": "...",
        "lab": "..."
      },
      "distance": 1.4199999570846558
    }
  ]
}
```

### `https://z87.ai/api/colors/similar/{id}`

Cross-brand matching from an existing color. Find this color in another brand.

| Param | Type | Required | Default |
|-------|------|----------|---------|
| brand | string | no | — |
| is_paint | bool | no | — |
| family | string | no | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/colors/similar/0?brand=behr&limit=1`

**Response:**
```json
{
  "source": {
    "id": 0,
    "name": "Saharagelb",
    "brand": "avery",
    "code": "526-G",
    "hex": "F3DC00",
    "rgb": [243, "...2 more"],
    "lrv": 70.23999786376953,
    "family": "yellow"
  },
  "results": [
    {
      "color": {
        "id": 988,
        "name": "Neon Light",
        "brand": "behr",
        "code": "380B-5",
        "hex": "FDE33E",
        "rgb": "...",
        "hsl": "...",
        "lab": "..."
      },
      "distance": 2.6700000762939453
    }
  ]
}
```

### `https://z87.ai/api/colors/harmonies/{id}`

Color harmonies (complementary, analogous, triadic, split-complementary, tetradic) resolved to real paint colors

| Param | Type | Required | Default |
|-------|------|----------|---------|
| brand | string | no | — |
| is_paint | bool | no | — |

**Example:** `GET https://z87.ai/api/colors/harmonies/0`

**Response:**
```json
{
  "source": {
    "id": 0,
    "name": "Saharagelb",
    "brand": "avery",
    "code": "526-G",
    "hex": "F3DC00",
    "rgb": [243, "...2 more"],
    "lrv": 70.23999786376953,
    "family": "yellow"
  },
  "schemes": [{"scheme": "complementary", "colors": ["..."]}, "...4 more"]
}
```

### `https://z87.ai/api/colors/strip/{id}`

Monochromatic coordinating colors from the same paint strip (mainly Sherwin-Williams)

No parameters.

**Example:** `GET https://z87.ai/api/colors/strip/0`

### `https://z87.ai/api/colors/palette/{id}`

Generate wall/trim/accent/ceiling palette from one color

| Param | Type | Required | Default |
|-------|------|----------|---------|
| brand | string | no | — |

**Example:** `GET https://z87.ai/api/colors/palette/0`

**Response:**
```json
{
  "wall": {
    "id": 0,
    "name": "Saharagelb",
    "brand": "avery",
    "code": "526-G",
    "hex": "F3DC00",
    "rgb": [243, "...2 more"],
    "hsl": [54.0, "...2 more"],
    "lab": [87.12000274658203, "...2 more"]
  },
  "trim": {
    "id": 274,
    "name": "White",
    "brand": "avery",
    "code": "800",
    "hex": "F7F8F4",
    "rgb": [247, "...2 more"],
    "hsl": [75.0, "...2 more"],
    "lab": [97.41000366210938, "...2 more"]
  },
  "accent": {
    "id": 152,
    "name": "Brillant Blue",
    "brand": "avery",
    "code": "753",
    "hex": "284CBF",
    "rgb": [40, "...2 more"],
    "hsl": [226.0, "...2 more"],
    "lab": [36.709999084472656, "...2 more"]
  },
  "ceiling": {
    "id": 275,
    "name": "White Matt",
    "brand": "avery",
    "code": "830",
    "hex": "FAFAF7",
    "rgb": [250, "...2 more"],
    "hsl": [60.0, "...2 more"],
    "lab": [98.1999969482422, "...2 more"]
  }
}
```

### `https://z87.ai/api/colors/compare`

Side-by-side comparison of colors by ID or hex with CIEDE2000 distance

| Param | Type | Required | Default |
|-------|------|----------|---------|
| ids | string | no | — |
| hexes | string | no | — |

**Example:** `GET https://z87.ai/api/colors/compare?ids=0,1`

**Response:**
```json
{
  "colors": [
    {
      "color": {
        "id": 0,
        "name": "Saharagelb",
        "brand": "avery",
        "code": "526-G",
        "hex": "F3DC00",
        "rgb": "...",
        "hsl": "...",
        "lab": "..."
      }
    },
    "...1 more"
  ],
  "distances": [{"a": 0, "b": 1, "ciede2000": 6.329999923706055}]
}
```

### `https://z87.ai/api/colors/colors/{id}`

Full color detail by ID

No parameters.

**Example:** `GET https://z87.ai/api/colors/colors/0`

**Response:**
```json
{
  "id": 0,
  "name": "Saharagelb",
  "brand": "avery",
  "code": "526-G",
  "hex": "F3DC00",
  "rgb": [243, "...2 more"],
  "hsl": [54.0, "...2 more"],
  "lab": [87.12000274658203, "...2 more"]
}
```

### `https://z87.ai/api/colors/suggest`

Autocomplete color names by prefix

| Param | Type | Required | Default |
|-------|------|----------|---------|
| q | string | **yes** | — |
| limit | u32 | no | 20 |

**Example:** `GET https://z87.ai/api/colors/suggest?q=hale&limit=5`

**Response:**
```json
{"colors": [{"id": 8379, "name": "Hale Navy"}, "...2 more"]}
```

### `https://z87.ai/api/colors/random`

Random color. Filter by brand, is_paint, or family.

| Param | Type | Required | Default |
|-------|------|----------|---------|
| brand | string | no | — |
| is_paint | bool | no | — |
| family | string | no | — |

**Example:** `GET https://z87.ai/api/colors/random?is_paint=true`

**Response:**
```json
{
  "id": 29869,
  "name": "White",
  "brand": "benjamin-moore",
  "code": "PM-2",
  "hex": "EDEEEB",
  "rgb": [237, "...2 more"],
  "hsl": [80.0, "...2 more"],
  "lab": [93.9499969482422, "...2 more"]
}
```

### `https://z87.ai/api/colors/stats`

Dataset statistics: color count per brand and family distribution

No parameters.

**Example:** `GET https://z87.ai/api/colors/stats`

**Response:**
```json
{
  "total_colors": 29895,
  "fields": {
    "brand": [
      ["behr", 4656],
      ["benjamin-moore", 4118],
      ["vista", 2785],
      ["trumatch", 2091],
      ["ppg", 2088],
      ["valspar", 1764],
      ["dunn-edwards", 1696],
      ["neenah", 1609],
      ["sherwin-williams", 1526],
      ["hl", 1469],
      ["mpc", 1416],
      ["dic", 1280],
      ["toyo", 1050],
      ["kilz", 827],
      ["avery", 382],
      ["hks", 312],
      ["ral", 213],
      ["ikea", 200],
      ["farrow-ball", 132],
      ["colorhouse", 128],
      ["dutch", 101],
      ["kobra", 52]
    ],
    "family": [
      ["orange", 5659],
      ["yellow", 4004],
      ["red", 3965],
      ["green", 3774],
      ["blue", 3291],
      ["teal", 2921],
      ["gray", 1707],
      ["white", 1525],
      ["pink", 1307],
      ["purple", 764],
      ["neutral", 537],
      ["brown", 244],
      ["black", 197]
    ]
  }
}
```

## License

The z87 API code is MIT licensed. Each dataset carries its upstream license:
- **colors**: Color names are trademarks of their respective owners (Sherwin-Williams, Benjamin Moore, Behr, etc.). Hex values are independently measured screen approximations, not official color specifications. z87 is not affiliated with any paint manufacturer. Reference to trademarks is for identification and comparison only. Data provided as-is; do not use for color-critical applications without consulting physical samples. z87 API code is MIT.


---

## Other z87 Datasets

- [chess](https://z87.ai/api/chess/SKILL.md) — 1B+ Lichess games (2000+ Elo, 2013-2026)
- [companies_uk](https://z87.ai/api/companies_uk/SKILL.md) — 5.7M UK companies from Companies House
- [countries](https://z87.ai/api/countries/SKILL.md) — 247 countries with 282 indicators (57 static, 225 timeseries) across economics, health, demographics, energy, environment, education, and more
- [design](https://z87.ai/api/design/SKILL.md) — 1,003 production-grade frontend designs with HTML, screenshots, prompts, and structured metadata (26 categories, 40 styles, 4K+ tags)
- [food](https://z87.ai/api/food/SKILL.md) — Recipes, FDC ingredients, and food products: 13.5K recipes with nutrition, 8K+ FDC ingredients, curated products with Nutri-Score and NOVA ratings.
- [gbif](https://z87.ai/api/gbif/SKILL.md) — GBIF Backbone Taxonomy: 7.7 million taxa with full taxonomic hierarchy, synonym resolution, tree navigation, and full-text search across the tree of life.
- [gutenberg](https://z87.ai/api/gutenberg/SKILL.md) — 60,000 Project Gutenberg books with chapter-level access, BM25 full-text search, cover art, illustrations, and AI-generated tags (genre, mood, era, locations, five-word summaries).
- [holidays](https://z87.ai/api/holidays/SKILL.md) — 3,391 public holidays across 121 countries (2026–2027)
- [home](https://z87.ai/api/home/SKILL.md) — Unified smart home device database
- [jokes](https://z87.ai/api/jokes/SKILL.md) — 41,000 jokes from three sources, AI-tagged with category, rating, topics, and offensive score
- [manpages](https://z87.ai/api/manpages/SKILL.md) — 142K Linux man pages with AI-generated cheat cards, category tags, use-frequency scores, and plain-english descriptions
- [movies](https://z87.ai/api/movies/SKILL.md) — 360K+ movies with 40-axis taste profiles, cast, themes, ratings, and soundtrack data
- [mtg](https://z87.ai/api/mtg/SKILL.md) — 29K Magic: The Gathering cards with synergy graph engine, combo detection, and Commander deck builder.
- [music](https://z87.ai/api/music/SKILL.md) — 651K artists, 500K+ albums, 1M+ songs from MusicBrainz with genre, country, and member data
- [osm](https://z87.ai/api/osm/SKILL.md) — 46M+ OpenStreetMap POIs with Hilbert-curve spatial index and BM25 text search
- [podcast](https://z87.ai/api/podcast/SKILL.md) — 1M+ podcasts from PodcastIndex with categories, language, episode counts, popularity scores, and cadence estimates
- [restaurants](https://z87.ai/api/restaurants/SKILL.md) — 10K London restaurants with menus, Michelin stars, ingredient category scores (seafood, meat, game, etc.), and capacity data
- [solve](https://z87.ai/api/solve/SKILL.md) — Computation engine: symbolic algebra, statistics, regression, finance, graph algorithms, Monte Carlo simulation
- [wikipedia](https://z87.ai/api/wikipedia/SKILL.md) — 7.2 million English Wikipedia articles with full markdown content, infoboxes, inter-article links, and geographic coordinates.
- [wiktionary](https://z87.ai/api/wiktionary/SKILL.md) — 8M+ Wiktionary entries across 4,000+ languages

Full index: [https://z87.ai/api/SKILL.md](https://z87.ai/api/SKILL.md)