The Color API

Identify, convert and scheme colors with The Color API, the free keyless color service. Give it a color in any format, hex, rgb, hsl, hsv or cmyk, and get back its name, every other format and the text color that reads best on it; convert one value into another format; generate a monochrome, analogic, complementary, triad or quad scheme from a seed color; check how readable one color is on another against the WCAG contrast levels; pick a random color that a seed makes repeatable; or identify a whole list of brand colors in one step.

Actions

Action	What it does
Check service status	Check whether The Color API is answering, and how quickly.
Compare two colors	Compare two colors: how readable text in one is on the other, as the WCAG contrast ratio with a pass or fail at each level, and how far apart they look, as a colour difference where about 2 is the least a person notices and 100 is black against white.
Convert a color	Convert one color into another format and get the converted value as a string ready to paste into a stylesheet, a design tool or a message, with its components beside it.
Generate a color scheme	Generate a color scheme from a seed color: shades of the one hue, its neighbours on the color wheel, its opposite, or three or four hues evenly spaced around it.
Get a random color	Pick a color at random and identify it, for an accent, a label or a placeholder that should not be the same every time.
Identify a color	Identify one color: its name from a dataset of some two thousand named colors, the same color in hex, rgb, hsl, hsv, cmyk and XYZ, whether it is dark, the text color that reads best on it, and a link to a swatch image.
Identify several colors	Identify a list of colors in one step, up to 10 at a time, in the order given: a brand palette, the colors pulled out of a design file, the swatches in a spreadsheet column.

Check service status

Check whether The Color API is answering, and how quickly. 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

messagetext
onlinetrue/false
reachabletrue/false
response_time_msnumber
status_codenumber

Example output

{
  "message": "The Color API is up and answering.",
  "online": true,
  "reachable": true,
  "response_time_ms": 88.4,
  "status_code": 200
}

Compare two colors

Compare two colors: how readable text in one is on the other, as the WCAG contrast ratio with a pass or fail at each level, and how far apart they look, as a colour difference where about 2 is the least a person notices and 100 is black against white. Both colors come back fully identified, so a step can also tell whether they share a name or are the same color spelled two ways. The service has no route for any of this; both colors are identified and the rest is worked out here.

Inputs

Text or foreground colorcolortextRequired: The color, in any format The Color API reads: a hex code such as #0047AB or 0047AB, rgb(0,71,171), hsl(215,100%,34%), hsv(215,100%,67%) or cmyk(100,58,0,33). Three bare numbers are read as rgb, three with a percent sign as hsl and four as cmyk. Wire in a value from an earlier step, or type one.
Background or other colorothertextRequired: The color, in any format The Color API reads: a hex code such as #0047AB or 0047AB, rgb(0,71,171), hsl(215,100%,34%), hsv(215,100%,67%) or cmyk(100,58,0,33). Three bare numbers are read as rgb, three with a percent sign as hsl and four as cmyk. Wire in a value from an earlier step, or type one.

Outputs

colorobject
contrast_rationumber
darkertext
delta_enumber
gradetext
identicaltrue/false
lightertext
otherobject
same_nametrue/false
wcagobject

Example output

{
  "color": {
    "closest_named_hex": "#0047AB",
    "cmyk": {
      "c": 100,
      "k": 33,
      "m": 58,
      "value": "cmyk(100, 58, 0, 33)",
      "y": 0
    },
    "exact_match_name": true,
    "hex": "#0047AB",
    "hex_clean": "0047AB",
    "hsl": {
      "h": 215,
      "l": 34,
      "s": 100,
      "value": "hsl(215, 100%, 34%)"
    },
    "hsv": {
      "h": 215,
      "s": 100,
      "v": 67,
      "value": "hsv(215, 100%, 67%)"
    },
    "image_url": "https://www.thecolorapi.com/id?format=svg&hex=0047AB",
    "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=0047AB",
    "is_dark": true,
    "name": "Cobalt",
    "name_distance": 0,
    "rgb": {
      "b": 171,
      "g": 71,
      "r": 0,
      "value": "rgb(0, 71, 171)"
    },
    "text_color": "#FFFFFF",
    "xyz": {
      "value": "XYZ(10, 7, 39)",
      "x": 10,
      "y": 7,
      "z": 39
    }
  },
  "contrast_ratio": 8.44,
  "darker": "#0047AB",
  "delta_e": 91.9,
  "grade": "AAA",
  "identical": false,
  "lighter": "#FFFFFF",
  "other": {
    "closest_named_hex": "#FFFFFF",
    "cmyk": {
      "c": 0,
      "k": 0,
      "m": 0,
      "value": "cmyk(0, 0, 0, 0)",
      "y": 0
    },
    "exact_match_name": true,
    "hex": "#FFFFFF",
    "hex_clean": "FFFFFF",
    "hsl": {
      "h": 0,
      "l": 100,
      "s": 0,
      "value": "hsl(0, 0%, 100%)"
    },
    "hsv": {
      "h": 0,
      "s": 0,
      "v": 100,
      "value": "hsv(0, 0%, 100%)"
    },
    "image_url": "https://www.thecolorapi.com/id?format=svg&hex=FFFFFF",
    "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=FFFFFF",
    "is_dark": false,
    "name": "White",
    "name_distance": 0,
    "rgb": {
      "b": 255,
      "g": 255,
      "r": 255,
      "value": "rgb(255, 255, 255)"
    },
    "text_color": "#000000",
    "xyz": {
      "value": "XYZ(95, 100, 109)",
      "x": 95,
      "y": 100,
      "z": 109
    }
  },
  "same_name": false,
  "wcag": {
    "aa_large_text": true,
    "aa_normal_text": true,
    "aaa_large_text": true,
    "aaa_normal_text": true
  }
}

Convert a color

Convert one color into another format and get the converted value as a string ready to paste into a stylesheet, a design tool or a message, with its components beside it. Any of hex, rgb, hsl, hsv and cmyk converts to any other; the hex code and the name come back too, whatever the target.

Inputs

ColorcolortextRequired: The color, in any format The Color API reads: a hex code such as #0047AB or 0047AB, rgb(0,71,171), hsl(215,100%,34%), hsv(215,100%,67%) or cmyk(100,58,0,33). Three bare numbers are read as rgb, three with a percent sign as hsl and four as cmyk. Wire in a value from an earlier step, or type one.
Convert tototextRequired: The format to convert the color into.One of: hex, rgb, hsl, hsv, cmyk.
Color formatcolor_formattext: Which format the color is written in. Leave empty to work it out from the value, which is right for anything but a bare hsv triple: 215,100%,67% reads as hsl unless this says HSV.One of: hex, rgb, hsl, hsv, cmyk.

Outputs

componentsobject
hextext
inputtext
input_formattext
nametext
totext
valuetext

Example output

{
  "components": {
    "h": 215,
    "l": 34,
    "s": 100
  },
  "hex": "#0047AB",
  "input": "#0047AB",
  "input_format": "hex",
  "name": "Cobalt",
  "to": "hsl",
  "value": "hsl(215, 100%, 34%)"
}

Generate a color scheme

Generate a color scheme from a seed color: shades of the one hue, its neighbours on the color wheel, its opposite, or three or four hues evenly spaced around it. Every color in the scheme comes back fully identified, with its name and every format, and the hex codes as a plain list for a step that only wants those. Ask for 1 to 19 colors; the service's own default is 5.

Inputs

Seed colorcolortextRequired: The color, in any format The Color API reads: a hex code such as #0047AB or 0047AB, rgb(0,71,171), hsl(215,100%,34%), hsv(215,100%,67%) or cmyk(100,58,0,33). Three bare numbers are read as rgb, three with a percent sign as hsl and four as cmyk. Wire in a value from an earlier step, or type one.
Schememodetext: How the scheme is built from the seed. Monochrome keeps the hue and varies the lightness; analogic takes the neighbouring hues; complement takes the opposite hue; triad and quad space three or four hues evenly. Defaults to monochrome.One of: monochrome, monochrome-dark (Monochrome, darker), monochrome-light (Monochrome, lighter), analogic (Analogic (neighbouring hues)), complement (Complement (the opposite hue)), analogic-complement (Analogic complement), triad (Triad (three hues evenly spaced)), quad (Quad (four hues evenly spaced)).
Number of colorscountnumber: How many colors to generate, from 1 to 19. Defaults to 5.From 1 to 19.
Color formatcolor_formattext: Which format the color is written in. Leave empty to work it out from the value, which is right for anything but a bare hsv triple: 215,100%,67% reads as hsl unless this says HSV.One of: hex, rgb, hsl, hsv, cmyk.

Outputs

color_countnumber
colorslist
countnumber
hex_valueslist
image_urltext
image_url_baretext
inputtext
input_formattext
modetext
requested_countnumber
seedobject

Example output

{
  "color_count": 2,
  "colors": [
    {
      "closest_named_hex": "#FF0000",
      "cmyk": {
        "c": 0,
        "k": 0,
        "m": 100,
        "value": "cmyk(0, 100, 100, 0)",
        "y": 100
      },
      "exact_match_name": true,
      "hex": "#FF0000",
      "hex_clean": "FF0000",
      "hsl": {
        "h": 0,
        "l": 50,
        "s": 100,
        "value": "hsl(0, 100%, 50%)"
      },
      "hsv": {
        "h": 0,
        "s": 100,
        "v": 100,
        "value": "hsv(0, 100%, 100%)"
      },
      "image_url": "https://www.thecolorapi.com/id?format=svg&hex=FF0000",
      "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=FF0000",
      "is_dark": true,
      "name": "Red",
      "name_distance": 0,
      "rgb": {
        "b": 0,
        "g": 0,
        "r": 255,
        "value": "rgb(255, 0, 0)"
      },
      "text_color": "#FFFFFF",
      "xyz": {
        "value": "XYZ(41, 21, 2)",
        "x": 41,
        "y": 21,
        "z": 2
      }
    },
    {
      "closest_named_hex": "#00FFFF",
      "cmyk": {
        "c": 100,
        "k": 0,
        "m": 0,
        "value": "cmyk(100, 0, 0, 0)",
        "y": 0
      },
      "exact_match_name": true,
      "hex": "#00FFFF",
      "hex_clean": "00FFFF",
      "hsl": {
        "h": 180,
        "l": 50,
        "s": 100,
        "value": "hsl(180, 100%, 50%)"
      },
      "hsv": {
        "h": 180,
        "s": 100,
        "v": 100,
        "value": "hsv(180, 100%, 100%)"
      },
      "image_url": "https://www.thecolorapi.com/id?format=svg&hex=00FFFF",
      "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=00FFFF",
      "is_dark": false,
      "name": "Cyan / Aqua",
      "name_distance": 0,
      "rgb": {
        "b": 255,
        "g": 255,
        "r": 0,
        "value": "rgb(0, 255, 255)"
      },
      "text_color": "#000000",
      "xyz": {
        "value": "XYZ(54, 79, 107)",
        "x": 54,
        "y": 79,
        "z": 107
      }
    }
  ],
  "count": 2,
  "hex_values": [
    "#FF0000",
    "#00FFFF"
  ],
  "image_url": "https://www.thecolorapi.com/scheme?format=svg&hex=FF0000&mode=complement&count=2",
  "image_url_bare": "https://www.thecolorapi.com/scheme?format=svg&named=false&hex=FF0000&mode=complement&count=2",
  "input": "#FF0000",
  "input_format": "hex",
  "mode": "complement",
  "requested_count": 2,
  "seed": {
    "closest_named_hex": "#FF0000",
    "cmyk": {
      "c": 0,
      "k": 0,
      "m": 100,
      "value": "cmyk(0, 100, 100, 0)",
      "y": 100
    },
    "exact_match_name": true,
    "hex": "#FF0000",
    "hex_clean": "FF0000",
    "hsl": {
      "h": 0,
      "l": 50,
      "s": 100,
      "value": "hsl(0, 100%, 50%)"
    },
    "hsv": {
      "h": 0,
      "s": 100,
      "v": 100,
      "value": "hsv(0, 100%, 100%)"
    },
    "image_url": "https://www.thecolorapi.com/id?format=svg&hex=FF0000",
    "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=FF0000",
    "is_dark": true,
    "name": "Red",
    "name_distance": 0,
    "rgb": {
      "b": 0,
      "g": 0,
      "r": 255,
      "value": "rgb(255, 0, 0)"
    },
    "text_color": "#FFFFFF",
    "xyz": {
      "value": "XYZ(41, 21, 2)",
      "x": 41,
      "y": 21,
      "z": 2
    }
  }
}

Get a random color

Pick a color at random and identify it, for an accent, a label or a placeholder that should not be the same every time. Add a seed to make the pick repeatable: the same seed always gives the same color, so naming a customer, a project or a date here gives each its own color that a later run finds again.

Inputs

Seedseedtext: Any text you like. The same seed always gives the same color, and a different seed almost always gives a different one. Leave empty for a fresh random color on every run.

Outputs

colorobject
seedtext

Example output

{
  "color": {
    "closest_named_hex": "#24B1E0",
    "cmyk": {
      "c": 84,
      "k": 12,
      "m": 21,
      "value": "cmyk(84, 21, 0, 12)",
      "y": 0
    },
    "exact_match_name": true,
    "hex": "#24B1E0",
    "hex_clean": "24B1E0",
    "hsl": {
      "h": 195,
      "l": 51,
      "s": 75,
      "value": "hsl(195, 75%, 51%)"
    },
    "hsv": {
      "h": 195,
      "s": 84,
      "v": 88,
      "value": "hsv(195, 84%, 88%)"
    },
    "image_url": "https://www.thecolorapi.com/id?format=svg&hex=24B1E0",
    "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=24B1E0",
    "is_dark": false,
    "name": "Cerulean",
    "name_distance": 0,
    "rgb": {
      "b": 224,
      "g": 177,
      "r": 36,
      "value": "rgb(36, 177, 224)"
    },
    "text_color": "#000000",
    "xyz": {
      "value": "XYZ(30, 37, 76)",
      "x": 30,
      "y": 37,
      "z": 76
    }
  },
  "seed": null
}

Identify a color

Identify one color: its name from a dataset of some two thousand named colors, the same color in hex, rgb, hsl, hsv, cmyk and XYZ, whether it is dark, the text color that reads best on it, and a link to a swatch image. Give it the color in any of those formats. A malformed color is refused here with a message, because the service itself would quietly identify it as black.

Inputs

ColorcolortextRequired: The color, in any format The Color API reads: a hex code such as #0047AB or 0047AB, rgb(0,71,171), hsl(215,100%,34%), hsv(215,100%,67%) or cmyk(100,58,0,33). Three bare numbers are read as rgb, three with a percent sign as hsl and four as cmyk. Wire in a value from an earlier step, or type one.
Color formatcolor_formattext: Which format the color is written in. Leave empty to work it out from the value, which is right for anything but a bare hsv triple: 215,100%,67% reads as hsl unless this says HSV.One of: hex, rgb, hsl, hsv, cmyk.

Outputs

colorobject
inputtext
input_formattext

Example output

{
  "color": {
    "closest_named_hex": "#0047AB",
    "cmyk": {
      "c": 100,
      "k": 33,
      "m": 58,
      "value": "cmyk(100, 58, 0, 33)",
      "y": 0
    },
    "exact_match_name": true,
    "hex": "#0047AB",
    "hex_clean": "0047AB",
    "hsl": {
      "h": 215,
      "l": 34,
      "s": 100,
      "value": "hsl(215, 100%, 34%)"
    },
    "hsv": {
      "h": 215,
      "s": 100,
      "v": 67,
      "value": "hsv(215, 100%, 67%)"
    },
    "image_url": "https://www.thecolorapi.com/id?format=svg&hex=0047AB",
    "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=0047AB",
    "is_dark": true,
    "name": "Cobalt",
    "name_distance": 0,
    "rgb": {
      "b": 171,
      "g": 71,
      "r": 0,
      "value": "rgb(0, 71, 171)"
    },
    "text_color": "#FFFFFF",
    "xyz": {
      "value": "XYZ(10, 7, 39)",
      "x": 10,
      "y": 7,
      "z": 39
    }
  },
  "input": "#0047AB",
  "input_format": "hex"
}

Identify several colors

Identify a list of colors in one step, up to 10 at a time, in the order given: a brand palette, the colors pulled out of a design file, the swatches in a spreadsheet column. Each is looked up as Identify a color does, one request each, and the names and hex codes come back as plain lists beside the full records. Every entry is checked before the first request is made, so a bad one fails the step without spending requests on the good ones ahead of it.

Inputs

ColorscolorslistRequired: The colors to identify, one per entry, each in any format The Color API reads. Wire a list in from an earlier step, or type them one per line.
Color formatcolor_formattext: Which format the color is written in. Leave empty to work it out from the value, which is right for anything but a bare hsv triple: 215,100%,67% reads as hsl unless this says HSV.One of: hex, rgb, hsl, hsv, cmyk.

Outputs

color_countnumber
colorslist
hex_valueslist
inputslist
nameslist

Example output

{
  "color_count": 2,
  "colors": [
    {
      "closest_named_hex": "#0047AB",
      "cmyk": {
        "c": 100,
        "k": 33,
        "m": 58,
        "value": "cmyk(100, 58, 0, 33)",
        "y": 0
      },
      "exact_match_name": true,
      "hex": "#0047AB",
      "hex_clean": "0047AB",
      "hsl": {
        "h": 215,
        "l": 34,
        "s": 100,
        "value": "hsl(215, 100%, 34%)"
      },
      "hsv": {
        "h": 215,
        "s": 100,
        "v": 67,
        "value": "hsv(215, 100%, 67%)"
      },
      "image_url": "https://www.thecolorapi.com/id?format=svg&hex=0047AB",
      "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=0047AB",
      "is_dark": true,
      "name": "Cobalt",
      "name_distance": 0,
      "rgb": {
        "b": 171,
        "g": 71,
        "r": 0,
        "value": "rgb(0, 71, 171)"
      },
      "text_color": "#FFFFFF",
      "xyz": {
        "value": "XYZ(10, 7, 39)",
        "x": 10,
        "y": 7,
        "z": 39
      }
    },
    {
      "closest_named_hex": "#24B1E0",
      "cmyk": {
        "c": 84,
        "k": 12,
        "m": 21,
        "value": "cmyk(84, 21, 0, 12)",
        "y": 0
      },
      "exact_match_name": true,
      "hex": "#24B1E0",
      "hex_clean": "24B1E0",
      "hsl": {
        "h": 195,
        "l": 51,
        "s": 75,
        "value": "hsl(195, 75%, 51%)"
      },
      "hsv": {
        "h": 195,
        "s": 84,
        "v": 88,
        "value": "hsv(195, 84%, 88%)"
      },
      "image_url": "https://www.thecolorapi.com/id?format=svg&hex=24B1E0",
      "image_url_bare": "https://www.thecolorapi.com/id?format=svg&named=false&hex=24B1E0",
      "is_dark": false,
      "name": "Cerulean",
      "name_distance": 0,
      "rgb": {
        "b": 224,
        "g": 177,
        "r": 36,
        "value": "rgb(36, 177, 224)"
      },
      "text_color": "#000000",
      "xyz": {
        "value": "XYZ(30, 37, 76)",
        "x": 30,
        "y": 37,
        "z": 76
      }
    }
  ],
  "hex_values": [
    "#0047AB",
    "#24B1E0"
  ],
  "inputs": [
    "#0047AB",
    "rgb(36,177,224)"
  ],
  "names": [
    "Cobalt",
    "Cerulean"
  ]
}

ActionsCopy Anchor Link

Check service statusCopy Anchor Link

Inputs

Outputs

Compare two colorsCopy Anchor Link

Inputs

Outputs

Convert a colorCopy Anchor Link

Inputs

Outputs

Generate a color schemeCopy Anchor Link

Inputs

Outputs

Get a random colorCopy Anchor Link

Inputs

Outputs

Identify a colorCopy Anchor Link

Inputs

Outputs

Identify several colorsCopy Anchor Link

Inputs

Outputs

On this page

Actions

Check service status

Compare two colors

Convert a color

Generate a color scheme

Get a random color

Identify a color

Identify several colors