Skip to main content

WCAG 2.2 Color Contrast Checker API

REAL DATA

Calculate WCAG 2.2 contrast for two opaque sRGB hex colors, including exact relative luminance and AA/AAA normal- and large-text results.

Authoritative reference data or standards computation

Base URL
/api/color-contrast
Category
Design & Media
Capabilities
1 route
Last updated
July 29, 2026
Data source

GET /api/color-contrast/check Calculate WCAG 2.2 contrast and AA/AAA text results

Canonicalizes two opaque sRGB hex colors, returns their relative luminance and evaluates the four WCAG text thresholds.

Live requestRuns against the public API
No key required
GET/api/color-contrast/check?foreground=%23111827&background=%23ffffff

Request parameters

Opaque foreground sRGB color in #rgb or #rrggbb notation. The # must be URL-encoded as %23 in a request URL.

Opaque background sRGB color in #rgb or #rrggbb notation. Alpha and non-hex CSS color syntax are rejected.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/color-contrast/check?foreground=%23111827&background=%23ffffff"
const res = await fetch("https://randomapi.dev/api/color-contrast/check?foreground=%23111827&background=%23ffffff");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/color-contrast/check?foreground=%23111827&background=%23ffffff").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/color-contrast/check?foreground=%23111827&background=%23ffffff"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
foreground string required

Opaque foreground sRGB color in #rgb or #rrggbb notation. The # must be URL-encoded as %23 in a request URL.

allowed: 1 – 32
example: foreground=#111827
background string required

Opaque background sRGB color in #rgb or #rrggbb notation. Alpha and non-hex CSS color syntax are rejected.

allowed: 1 – 32
example: background=#ffffff
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=foreground,background
exclude list

Return all fields except these (comma-separated).

example: exclude=passesAaaLargeText
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 9
foreground string (hex color)

Canonical lowercase six-digit foreground color.

example: #111827

background string (hex color)

Canonical lowercase six-digit background color.

example: #ffffff

foregroundLuminance float

WCAG relative luminance of the foreground, from 0 through 1.

example: 0.009955

backgroundLuminance float

WCAG relative luminance of the background, from 0 through 1.

example: 1

contrastRatio float

WCAG contrast ratio from 1 through 21.

example: 17.739

passesAaNormalText boolean

Whether the ratio is at least 4.5:1 for WCAG AA normal text.

example: true

passesAaLargeText boolean

Whether the ratio is at least 3:1 for WCAG AA large text.

example: true

passesAaaNormalText boolean

Whether the ratio is at least 7:1 for WCAG AAA normal text.

example: true

passesAaaLargeText boolean

Whether the ratio is at least 4.5:1 for WCAG AAA large text.

example: true

Documented examples

Build-generated requests and complete responses 3
Check near-black text on white
GET /api/color-contrast/check?foreground=%23111827&background=%23ffffff 
{
  "data": {
    "foreground": "#111827",
    "background": "#ffffff",
    "foregroundLuminance": 0.009189219295824108,
    "backgroundLuminance": 1,
    "contrastRatio": 17.73971700407407,
    "passesAaNormalText": true,
    "passesAaLargeText": true,
    "passesAaaNormalText": true,
    "passesAaaLargeText": true
  },
  "meta": {
    "endpoint": "color-contrast",
    "route": "/check",
    "params": {
      "foreground": "#111827",
      "background": "#ffffff"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Check white text on a blue background
GET /api/color-contrast/check?foreground=%23fff&background=%232563eb 
{
  "data": {
    "foreground": "#ffffff",
    "background": "#2563eb",
    "foregroundLuminance": 1,
    "backgroundLuminance": 0.15315153582201535,
    "contrastRatio": 5.168555560022562,
    "passesAaNormalText": true,
    "passesAaLargeText": true,
    "passesAaaNormalText": false,
    "passesAaaLargeText": true
  },
  "meta": {
    "endpoint": "color-contrast",
    "route": "/check",
    "params": {
      "foreground": "#ffffff",
      "background": "#2563eb"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Inspect a failing low-contrast pair
GET /api/color-contrast/check?foreground=%23777&background=%23fff 
{
  "data": {
    "foreground": "#777777",
    "background": "#ffffff",
    "foregroundLuminance": 0.184474994500441,
    "backgroundLuminance": 1,
    "contrastRatio": 4.478089453577214,
    "passesAaNormalText": false,
    "passesAaLargeText": true,
    "passesAaaNormalText": false,
    "passesAaaLargeText": false
  },
  "meta": {
    "endpoint": "color-contrast",
    "route": "/check",
    "params": {
      "foreground": "#777777",
      "background": "#ffffff"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Checks two opaque sRGB colors against the contrast-ratio requirements in WCAG 2.2. Pass a foreground and background in strict #rgb or #rrggbb notation; shorthand is expanded and both inputs are canonicalized to lowercase six-digit hex in the response and meta.params.

Each sRGB channel is linearized with the current WCAG breakpoint of 0.04045, then combined as 0.2126 R + 0.7152 G + 0.0722 B. The lighter and darker relative luminances produce (L1 + 0.05) / (L2 + 0.05), a ratio from 1 to 21.

The four booleans apply the WCAG thresholds directly: AA normal text ≥4.5, AA large text ≥3, AAA normal text ≥7 and AAA large text ≥4.5. “Large” has the WCAG meaning (at least 18 point, or 14 point when bold); this API evaluates contrast only and does not infer a font's size or weight.

Alpha, CSS names, rgb(), wide-gamut color spaces and gradients are deliberately rejected. Transparent colors require compositing against a known background first, so accepting them here would create a misleading ratio.

Use it for

  • Gate design tokens against WCAG AA and AAA text-contrast requirements
  • Show immediate accessibility feedback in a theme or color picker
  • Audit foreground/background pairs in a component library test suite
  • Verify generated chart labels and UI states before rendering them

Frequently asked questions

Practical answers about this endpoint 4
Which WCAG contrast thresholds does the API check?

It checks AA normal text at 4.5:1, AA large text at 3:1, AAA normal text at 7:1 and AAA large text at 4.5:1.

Does the luminance calculation use the WCAG 2.2 sRGB formula?

Yes. It linearizes sRGB channels with the current 0.04045 breakpoint and applies the WCAG relative-luminance coefficients before calculating the ratio.

Can I check a transparent foreground color?

No. Alpha is rejected because contrast depends on compositing; provide the final opaque foreground and background colors instead.

Which color formats are accepted?

Only opaque #rgb and #rrggbb sRGB hex values are accepted. Encode the # as %23 in a URL.

Standards & references

Primary sources behind the contract

Related APIs

Useful next tools in the catalog
Random Color API MOCK DATA

Random colors in hex, RGB and HSL with hue and luminosity filters, nearest CSS color names and WCAG contrast text — plus deterministic color-scheme palettes.
SVG Sparkline & Chart Placeholder API MOCK DATA

Sparkline SVGs straight from a URL — plot 2–100 numbers as a line, area or bar chart with custom size, color and smoothing. No chart library needed.
Placeholder Image API MOCK DATA

Hotlinkable SVG placeholder images at any size from 8 to 4000 px — custom label, colors and an optional gradient. Deterministic and crisp at every scale.
Avatar Placeholder API MOCK DATA

Deterministic SVG avatars from any seed string — identicons, initials and abstract shapes. Same seed, same avatar forever; plus ready-to-use avatar URL batches.
Barcode Generator API REAL DATA

Real, scannable SVG barcodes — EAN-13 with automatic check digits and Code 128 set B. Custom height, optional label, deterministic and safe to hotlink.
Color Blindness Simulator API for Hex Colors & Palettes REAL DATA

Simulate protanopia, deuteranopia and tritanopia on your colors with cited Brettel 1997, Viénot 1999 or Machado 2009 matrices, and flag pairs that converge.