# OpenColors

> Look up any color on OpenColors, the free keyless color data API. Turn a hex code into RGB, HSL, HSV and CMYK, find out whether someone has named it and who, or get the nearest named color and how far off it is. Check a color's WCAG 2.1 contrast against white and black, see it as people with each kind of color blindness do, check which of up to a hundred colors are still unnamed in one request, search the colors people have named, and pull the official palettes of more than 600 brands, from Spotify's green to Netflix's red.

App · Images & Design · 10 actions. Web page: https://docs.lodol.com/docs/integrations/opencolors

## Actions

### Check color availability

Check which of up to 100 colors are still unnamed on OpenColors, in one request. Each color comes back as available or already named, with the name and owner when it is taken, and the two lists are summarised so a step can branch on the counts or take the available hexes straight into the next step.

**Inputs**

- Colors (`hexes`, list, required): The colors to check, one per entry, in any hex spelling. Up to 100 at a time; a repeat is checked once. A single text of colors separated by commas works too.

**Outputs**

- `available_count` (number)
- `available_hexes` (list)
- `color_count` (number)
- `colors` (list)
- `named_count` (number)
- `named_hexes` (list)
- `requested_count` (number)
- `unanswered_hexes` (list)

**Example output**

```json
{
  "available_count": 1,
  "available_hexes": [
    "3366CC"
  ],
  "color_count": 2,
  "colors": [
    {
      "available": false,
      "css": "#FF5733",
      "hex": "FF5733",
      "hex_int": 16734003,
      "is_named": true,
      "name": "Sunset Orange",
      "owner": "John Doe"
    },
    {
      "available": true,
      "css": "#3366CC",
      "hex": "3366CC",
      "hex_int": 3368652,
      "is_named": false,
      "name": null,
      "owner": null
    }
  ],
  "named_count": 1,
  "named_hexes": [
    "FF5733"
  ],
  "requested_count": 2,
  "unanswered_hexes": []
}
```

### Check service status

Check whether OpenColors is answering, how quickly, and what it reports about itself: its own status, the state of its database and its version. This is the one action that reports a problem as a value instead of failing the step, so a workflow can decide what to do about it.

**Inputs**: None.

**Outputs**

- `database_status` (text)
- `message` (text)
- `online` (true/false)
- `reachable` (true/false)
- `reported_status` (text)
- `response_time_ms` (number)
- `status_code` (number)
- `version` (text)

**Example output**

```json
{
  "database_status": "healthy",
  "message": "OpenColors 1.0.0 is up and answering.",
  "online": true,
  "reachable": true,
  "reported_status": "healthy",
  "response_time_ms": 45.0,
  "status_code": 200,
  "version": "1.0.0"
}
```

### Check WCAG contrast

Check a color's WCAG 2.1 contrast against a white and a black background: the ratio on each, whether it passes AA and AAA for small text, large text and UI components, which of the two it reads best on, and the text color OpenColors recommends for anything written on top of it. Built for checking a brand color before it goes on a page.

**Inputs**

- Color (`hex`, text, required): The color, as a hex code: FF5733, #FF5733 or the three-digit shorthand F53 all work, as does the number OpenColors itself hands back for a color. Anything else is refused here with a message rather than by the service.

**Outputs**

- `best_background` (text)
- `css` (text)
- `hex` (text)
- `on_black` (object)
- `on_white` (object)
- `recommended_text_color` (text)
- `rgb` (object)

**Example output**

```json
{
  "best_background": "black",
  "css": "#FF5733",
  "hex": "FF5733",
  "on_black": {
    "large_text": {
      "aa": true,
      "aaa": true
    },
    "ratio": 6.67,
    "small_text": {
      "aa": true,
      "aaa": false
    },
    "ui_components": {
      "aa": true,
      "aaa": true
    }
  },
  "on_white": {
    "large_text": {
      "aa": true,
      "aaa": false
    },
    "ratio": 3.15,
    "small_text": {
      "aa": false,
      "aaa": false
    },
    "ui_components": {
      "aa": true,
      "aaa": true
    }
  },
  "recommended_text_color": "dark",
  "rgb": {
    "b": 51,
    "g": 87,
    "r": 255
  }
}
```

### Get a brand's colors

Get one brand's official palette by name. The service only searches, so the name is searched for and matched here: an exact name or slug always wins, and failing that a partial name resolves when it lands on a single brand, so 'spotify' and 'the Spotify brand' both work. A name matching two brands is reported with both rather than guessed between.

**Inputs**

- Brand (`brand`, text, required): The brand to look up, by name or slug. A partial name works when only one brand matches it.

**Outputs**

- `brand` (object)
- `matched_exactly` (true/false)
- `requested_brand` (text)

**Example output**

```json
{
  "brand": {
    "brand_url": "https://www.spotify.com/",
    "color_count": 2,
    "colors": [
      {
        "css": "#1DB954",
        "hex": "1DB954"
      },
      {
        "css": "#191414",
        "hex": "191414"
      }
    ],
    "id": "abc123",
    "name": "Spotify",
    "slug": "spotify",
    "source_url": "https://developer.spotify.com/design/"
  },
  "matched_exactly": true,
  "requested_brand": "Spotify"
}
```

### Get color statistics

Get the state of the OpenColors catalogue: how many of the 16.7 million colors have been named, how many are still available, how many were named recently, the size of the partner programme, and who has named the most colors.

**Inputs**: None.

**Outputs**

- `available_colors` (number)
- `named_colors` (number)
- `partner_credits` (number)
- `partners` (number)
- `recent_transactions` (number)
- `recently_named` (number)
- `top_owners` (list)
- `total_colors` (number)

**Example output**

```json
{
  "available_colors": 16654766,
  "named_colors": 1250,
  "partner_credits": 500,
  "partners": 15,
  "recent_transactions": 5,
  "recently_named": 23,
  "top_owners": [
    {
      "count": 45,
      "name": "John Doe"
    },
    {
      "count": 32,
      "name": "Jane Smith"
    }
  ],
  "total_colors": 16777216
}
```

### Look up a color

Look up any hex code and get it in every color model: RGB, HSL, HSV and CMYK, with the text color that reads best on it. Says whether someone has named the color, and who, and for an unnamed color gives the nearest named one with its distance. Switch on the WCAG contrast check and the color blindness simulations to get everything in the one request.

**Inputs**

- Color (`hex`, text, required): The color, as a hex code: FF5733, #FF5733 or the three-digit shorthand F53 all work, as does the number OpenColors itself hands back for a color. Anything else is refused here with a message rather than by the service.
- Include WCAG contrast (`include_accessibility`, true/false): Also return the WCAG 2.1 contrast ratios against white and black, with the AA and AAA verdicts for small text, large text and UI components. Off by default. Default: `false`.
- Include color blindness simulations (`include_colorblind`, true/false): Also return how the color looks with protanopia, deuteranopia, tritanopia and achromatopsia. Off by default. Default: `false`.

**Outputs**

- `accessibility` (object)
- `claimed_at` (text)
- `color` (object)
- `colorblind` (object)
- `dedication` (text)
- `is_named` (true/false)
- `name` (text)
- `nearest` (object)
- `owner` (text)

**Example output**

```json
{
  "accessibility": {
    "best_background": "black",
    "on_black": {
      "large_text": {
        "aa": true,
        "aaa": true
      },
      "ratio": 6.67,
      "small_text": {
        "aa": true,
        "aaa": false
      },
      "ui_components": {
        "aa": true,
        "aaa": true
      }
    },
    "on_white": {
      "large_text": {
        "aa": true,
        "aaa": false
      },
      "ratio": 3.15,
      "small_text": {
        "aa": false,
        "aaa": false
      },
      "ui_components": {
        "aa": true,
        "aaa": true
      }
    }
  },
  "claimed_at": null,
  "color": {
    "cmyk": {
      "c": 0,
      "k": 0,
      "m": 66,
      "y": 80
    },
    "css": "#FF5733",
    "hex": "FF5733",
    "hex_int": 16734003,
    "hsl": {
      "h": 11,
      "l": 60,
      "s": 100
    },
    "hsv": {
      "h": 11,
      "s": 80,
      "v": 100
    },
    "recommended_text_color": "dark",
    "rgb": {
      "b": 51,
      "g": 87,
      "r": 255
    }
  },
  "colorblind": {
    "achromatopsia": {
      "css": "#959595",
      "hex": "959595",
      "label": "Complete color blindness",
      "rgb": {
        "b": 149,
        "g": 149,
        "r": 149
      }
    },
    "deuteranopia": {
      "css": "#E89333",
      "hex": "E89333",
      "label": "Green-blind",
      "rgb": {
        "b": 51,
        "g": 147,
        "r": 232
      }
    },
    "protanopia": {
      "css": "#D69433",
      "hex": "D69433",
      "label": "Red-blind",
      "rgb": {
        "b": 51,
        "g": 148,
        "r": 214
      }
    },
    "tritanopia": {
      "css": "#F34554",
      "hex": "F34554",
      "label": "Blue-blind",
      "rgb": {
        "b": 84,
        "g": 69,
        "r": 243
      }
    }
  },
  "dedication": null,
  "is_named": false,
  "name": null,
  "nearest": {
    "css": "#251706",
    "distance": 87.96,
    "hex": "251706",
    "hex_int": 2430726,
    "name": "Cannon Black",
    "rgb": {
      "b": 6,
      "g": 23,
      "r": 37
    },
    "similarity": "very different"
  },
  "owner": null
}
```

### Name a color

Get a name for any color: its own name if someone has named it, otherwise the nearest named color and how far off it is, as a distance and as a word from imperceptible to very different. One record either way, so a step that wants a word for a color never has to check which case it got.

**Inputs**

- Color (`hex`, text, required): The color, as a hex code: FF5733, #FF5733 or the three-digit shorthand F53 all work, as does the number OpenColors itself hands back for a color. Anything else is refused here with a message rather than by the service.

**Outputs**

- `css` (text)
- `distance` (number)
- `hex` (text)
- `is_named` (true/false)
- `name` (text)
- `name_css` (text)
- `name_hex` (text)
- `owner` (text)
- `similarity` (text)

**Example output**

```json
{
  "css": "#FF5733",
  "distance": 87.96,
  "hex": "FF5733",
  "is_named": false,
  "name": "Cannon Black",
  "name_css": "#251706",
  "name_hex": "251706",
  "owner": null,
  "similarity": "very different"
}
```

### Search brand colors

Search the official color palettes of more than 600 companies by brand name, or leave the search empty and page through all of them. Each brand comes back with its colors in the order it publishes them, each as a hex code and a CSS-ready one, plus the brand's site and the design page the palette was taken from.

**Inputs**

- Search for (`query`, text): Part of the brand's name. Leave empty to list every brand a page at a time.
- Number of brands (`limit`, number): How many brands to return, from 1 to 200. Defaults to 50, which is the service's own page size. From 1 to 200.
- Skip (`offset`, number): How many brands to skip before the first returned, for paging. The result says where the next page starts. At least 0.

**Outputs**

- `brand_count` (number)
- `brands` (list)
- `has_more` (true/false)
- `next_offset` (number)
- `offset` (number)
- `query` (text)
- `requested_count` (number)
- `total` (number)

**Example output**

```json
{
  "brand_count": 1,
  "brands": [
    {
      "brand_url": "https://www.spotify.com/",
      "color_count": 2,
      "colors": [
        {
          "css": "#1DB954",
          "hex": "1DB954"
        },
        {
          "css": "#191414",
          "hex": "191414"
        }
      ],
      "id": "abc123",
      "name": "Spotify",
      "slug": "spotify",
      "source_url": "https://developer.spotify.com/design/"
    }
  ],
  "has_more": false,
  "next_offset": null,
  "offset": 0,
  "query": "spotify",
  "requested_count": 10,
  "total": 1
}
```

### Search named colors

Search the colors people have named on OpenColors by name, and narrow to one owner. Sort by name, owner, hex or when the color was named, in either direction, and choose how many to return, up to 50. Each result carries the hex, the name, the owner and the dedication.

**Inputs**

- Search for (`query`, text, required): The word or phrase to look for in color names, at least 2 characters.
- Owner (`owner`, text): Only return colors named by this person. Leave empty for everyone's.
- Sort by (`sort`, text): What to order the results by. Defaults to name. One of: `name`, `owner`, `created_at` (When it was named), `hex` (Hex code). Default: `name`.
- Order (`order`, text): Ascending or descending. Defaults to ascending. One of: `asc` (Ascending), `desc` (Descending). Default: `asc`.
- Number of results (`limit`, number): How many colors to return, from 1 to 50. Defaults to 10. From 1 to 50.

**Outputs**

- `color_count` (number)
- `colors` (list)
- `order` (text)
- `owner` (text)
- `query` (text)
- `requested_count` (number)
- `sort` (text)
- `total` (number)

**Example output**

```json
{
  "color_count": 1,
  "colors": [
    {
      "claimed_at": "2024-01-15T10:30:00.000Z",
      "css": "#FF5733",
      "dedication": "To my family",
      "hex": "FF5733",
      "hex_int": 16734003,
      "name": "Sunset Orange",
      "owner": "John Doe"
    }
  ],
  "order": "asc",
  "owner": null,
  "query": "sunset",
  "requested_count": 10,
  "sort": "name",
  "total": 1
}
```

### Simulate color blindness

See how a color looks to people with each kind of color vision deficiency: protanopia (red-blind), deuteranopia (green-blind), tritanopia (blue-blind) and achromatopsia (complete color blindness). Each comes back as a hex code and RGB, ready to compare with the original or feed into another color action.

**Inputs**

- Color (`hex`, text, required): The color, as a hex code: FF5733, #FF5733 or the three-digit shorthand F53 all work, as does the number OpenColors itself hands back for a color. Anything else is refused here with a message rather than by the service.

**Outputs**

- `achromatopsia` (object)
- `css` (text)
- `deuteranopia` (object)
- `hex` (text)
- `protanopia` (object)
- `rgb` (object)
- `tritanopia` (object)

**Example output**

```json
{
  "achromatopsia": {
    "css": "#959595",
    "hex": "959595",
    "label": "Complete color blindness",
    "rgb": {
      "b": 149,
      "g": 149,
      "r": 149
    }
  },
  "css": "#FF5733",
  "deuteranopia": {
    "css": "#E89333",
    "hex": "E89333",
    "label": "Green-blind",
    "rgb": {
      "b": 51,
      "g": 147,
      "r": 232
    }
  },
  "hex": "FF5733",
  "protanopia": {
    "css": "#D69433",
    "hex": "D69433",
    "label": "Red-blind",
    "rgb": {
      "b": 51,
      "g": 148,
      "r": 214
    }
  },
  "rgb": {
    "b": 51,
    "g": 87,
    "r": 255
  },
  "tritanopia": {
    "css": "#F34554",
    "hex": "F34554",
    "label": "Blue-blind",
    "rgb": {
      "b": 84,
      "g": 69,
      "r": 243
    }
  }
}
```