Overview
Each `color1` and `color2` value has its `#` stripped and is read as hex. Three-digit shorthand is expanded (`F00` becomes `FF0000`) and the alpha byte of an eight-digit value is dropped, so transparency never affects the result. The channels are converted to HSL in the usual way, with hue in degrees and saturation and lightness as percentages, rounded to one decimal in the response.
`rgb_distance` is the straight-line distance between the two colors in 0-255 RGB space, and `rgb_similarity` rescales it to a percentage of the largest possible distance (black to white). `hsl_similarity` is built from the hue gap, measured around the color wheel so 350 and 10 degrees are 20 apart, plus the saturation and lightness gaps, each normalised to 0-1 before they are combined. `overall_similarity` is the plain average of those two percentages. `similarity_category` maps it with fixed cut-offs: 95 and above is nearly identical, 85 very similar, 70 similar, 50 somewhat similar, 30 different, and anything lower very different.
`delta_e` is CIE76: both colors are converted from sRGB to CIE-LAB under the D65 white point and the Euclidean distance is taken there, so it tracks perceived difference more closely than the RGB figures. All distances and percentages are rounded to two decimals. `are_identical` compares the normalised hex strings, so `#ff0000` and `FF0000` match, but a shorthand value and its six-digit form do not. On the Free plan the distance, Delta E, HSL similarity and per-channel difference fields come back null.
Live Test Color Similarity Calculator API →
Endpoint
One host, one path per API. The block below shows this call in four languages; every one of them is the same HTTP request. Making requests covers the timeouts, retries and parameter rules that apply to all of them. The SDKs wrap the same call in a typed client.
curl "https://api.apiverve.com/v1/colorsimilarity?color1=FF5733&color2=FF6B47" \
-H "x-api-key: your_api_key_here"const res = await fetch('https://api.apiverve.com/v1/colorsimilarity?color1=FF5733&color2=FF6B47', {
headers: { 'x-api-key': 'your_api_key_here' },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data } = await res.json();
console.log(data);import requests
res = requests.get(
"https://api.apiverve.com/v1/colorsimilarity?color1=FF5733&color2=FF6B47",
headers={"x-api-key": "your_api_key_here"},
timeout=15,
)
res.raise_for_status()
print(res.json()["data"])package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://api.apiverve.com/v1/colorsimilarity?color1=FF5733&color2=FF6B47", nil)
req.Header.Set("x-api-key", "your_api_key_here")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
out, _ := io.ReadAll(res.Body)
fmt.Println(string(out))
}Replace your_api_key_here with the key from your dashboard. When the inputs arrive as a list rather than one at a time, batch requests run up to 200 of them through this same API in a single call.
Authentication
Send your key in the x-api-key header. That is the only auth step — there is no token exchange and no per-endpoint scope to configure. Authentication covers creating, rotating and revoking keys.
A 401 means the key is missing, invalid or expired. A 403 means the key is valid but not permitted here — blocked by a key restriction or an IP allow-list. Running out of credits is a 429.
Parameters
Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them.
| Parameter | Type | Description |
|---|---|---|
color1Required | string | First hex color value (with or without # prefix) hexColor |
color2Required | string | Second hex color value (with or without # prefix) hexColor |
Response
Every API returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape. Response format covers the envelope, the other output formats and how premium fields are withheld.
{
"status": "ok",
"error": null,
"data": {
"color1": {
"hex": "#FF5733",
"rgb": {
"r": 255,
"g": 87,
"b": 51
},
"hsl": {
"h": 10.6,
"s": 100,
"l": 60
}
},
"color2": {
"hex": "#FF6B47",
"rgb": {
"r": 255,
"g": 107,
"b": 71
},
"hsl": {
"h": 11.7,
"s": 100,
"l": 63.9
}
},
"rgb_distance": 28.28,
"rgb_similarity": 93.6,
"hsl_similarity": 97.71,
"overall_similarity": 95.65,
"delta_e": 28.28,
"hue_difference": 1.15,
"saturation_difference": 0,
"lightness_difference": 3.92,
"similarity_category": "nearly identical",
"are_identical": false
}
}
Response fields
Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.
| Field | Type | Example | Description |
|---|---|---|---|
color1 | object | {...} | The first colour, in hex, RGB and HSL |
hex | string | "#FF5733" | First color in hexadecimal format representation |
rgb | object | {...} | First colour as red, green and blue channels |
r | number | 255 | Red channel value for first color |
g | number | 87 | Green channel value for first color |
b | number | 51 | Blue channel value for first color |
hsl | object | {...} | First colour as hue, saturation and lightness |
h | number | 10.6 | Hue value for first color in degrees |
s | number | 100 | Saturation percentage for first color |
l | number | 60 | Lightness percentage for first color |
color2 | object | {...} | The second colour, in hex, RGB and HSL |
hex | string | "#FF6B47" | Second color in hexadecimal format representation |
rgb | object | {...} | Second colour as red, green and blue channels |
r | number | 255 | Red channel value for second color |
g | number | 107 | Green channel value for second color |
b | number | 71 | Blue channel value for second color |
hsl | object | {...} | Second colour as hue, saturation and lightness |
h | number | 11.7 | Hue value for second color in degrees |
s | number | 100 | Saturation percentage for second color |
l | number | 63.9 | Lightness percentage for second color |
rgb_distancePremium | number | 28.28 | Euclidean distance between colors in RGB space |
rgb_similarityPremium | number | 93.6 | Percentage similarity based on RGB color space |
hsl_similarityPremium | number | 97.71 | Percentage similarity based on HSL color space |
overall_similarity | number | 95.65 | Combined similarity percentage from all algorithms |
delta_ePremium | number | 28.28 | Delta E color difference metric for perceptual similarity |
hue_differencePremium | number | 1.15 | Hue difference between colors in degrees |
saturation_differencePremium | number | 0 | Saturation percentage difference between colors |
lightness_differencePremium | number | 3.92 | Lightness percentage difference between colors |
similarity_category | string | "nearly identical" | Human readable category describing similarity level |
are_identical | boolean | false | Boolean indicating if colors are exactly identical |
Errors
Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change. Error handling covers the full status list and which of them are worth retrying.
| Status | Meaning | What to do |
|---|---|---|
400 | Input was rejected | Read error; it names the parameter. |
401 | Key missing or invalid | Check the header name and the key value. |
403 | Key valid, but not permitted | A key restriction or IP allow-list; see key scoping. |
429 | Rate limited, or out of credits | Read error to tell them apart; see rate limits. |
Use cases
- Color Matching
- Find and compare similar colors for design consistency and brand compliance
- Image Processing
- Compare colors in images for color correction and matching operations
- Design Systems
- Validate color palette consistency and identify similar colors in design systems
- Quality Control
- Compare product colors against standards for quality assurance and brand consistency
Other ways to use Color Similarity Calculator
Set up Color Similarity Calculator on APIVerve, or reach the same source a different way. Your APIVerve account and credits work on all of them — one key, one balance.
Related
More in Math/Calculations: