Developer API

Color Data API

A simple, free API for looking up color information. Get RGB, HSL values, check if a color is named, find the nearest named color, and access WCAG contrast ratios and colorblind simulations.

01Quick Start

GET/api/v1/color/:hex

curl "/api/v1/color/FF5733"

Optional Query Parameters:

?accessibility=trueInclude WCAG contrast ratios against white and black backgrounds

?colorblind=trueInclude colorblind simulations (protanopia, deuteranopia, tritanopia, achromatopsia)

02Try It Out

Include Accessibility DataInclude Colorblind Simulations

03Code Examples

async function getColorInfo(hex) {
  const response = await fetch(`/api/v1/color/${hex}`);
  const data = await response.json();
  
  if (data.isNamed) {
    console.log(`This color is named: ${data.data.name}`);
  } else {
    console.log(`Unnamed. Nearest: ${data.nearest.name}`);
  }
  
  return data;
}

getColorInfo('FF5733');

04Response Format

200 OKNamed Color

{
  "success": true,
  "color": {
    "hex": "FF5733",
    "hexInt": 16734003,
    "rgb": { "r": 255, "g": 87, "b": 51 },
    "hsl": { "h": 11, "s": 100, "l": 60 },
    "hsv": { "h": 11, "s": 80, "v": 100 },
    "cmyk": { "c": 0, "m": 66, "y": 80, "k": 0 },
    "contrast": "dark"
  },
  "isNamed": true,
  "data": {
    "name": "Sunset Orange",
    "owner": "John Doe",
    "dedicated": "To my family",
    "claimedAt": "2024-01-15T10:30:00.000Z"
  },
  "nearest": null
}

200 OKUnnamed Color (with nearest)

{
  "success": true,
  "color": {
    "hex": "FF5734",
    "hexInt": 16734004,
    "rgb": { "r": 255, "g": 87, "b": 52 },
    "hsl": { "h": 11, "s": 100, "l": 60 },
    "hsv": { "h": 11, "s": 80, "v": 100 },
    "cmyk": { "c": 0, "m": 66, "y": 80, "k": 0 },
    "contrast": "dark"
  },
  "isNamed": false,
  "data": null,
  "nearest": {
    "hex": "FF5733",
    "hexInt": 16734003,
    "name": "Sunset Orange",
    "distance": 0.45,
    "rgb": { "r": 255, "g": 87, "b": 51 }
  }
}

400 Bad RequestInvalid Hex

{
  "success": false,
  "error": "Invalid hex color format...",
  "code": "INVALID_HEX_FORMAT"
}

05Accessibility & Colorblind Simulations

GETWCAG Contrast Checker

curl "/api/v1/color/FF5733?accessibility=true"

Get WCAG 2.1 contrast ratios and compliance levels (AA/AAA) for small text, large text, and UI components on white and black backgrounds.

{
  "success": true,
  "color": {
    "hex": "FF5733",
    "rgb": { "r": 255, "g": 87, "b": 51 },
    ...
    "accessibility": {
      "onWhite": {
        "ratio": 3.15,
        "smallText": { "AA": false, "AAA": false },
        "largeText": { "AA": true, "AAA": false },
        "uiComponents": { "AA": true, "AAA": true }
      },
      "onBlack": {
        "ratio": 6.67,
        "smallText": { "AA": true, "AAA": false },
        "largeText": { "AA": true, "AAA": true },
        "uiComponents": { "AA": true, "AAA": true }
      }
    }
  },
  ...
}

GETColorblind Simulations

curl "/api/v1/color/FF5733?colorblind=true"

Simulate how the color appears to people with different types of color vision deficiency.

{
  "success": true,
  "color": {
    "hex": "FF5733",
    "rgb": { "r": 255, "g": 87, "b": 51 },
    ...
    "colorblind": {
      "protanopia": {
        "hex": "D69433",
        "rgb": { "r": 214, "g": 148, "b": 51 }
      },
      "deuteranopia": {
        "hex": "E89333",
        "rgb": { "r": 232, "g": 147, "b": 51 }
      },
      "tritanopia": {
        "hex": "F34554",
        "rgb": { "r": 243, "g": 69, "b": 84 }
      },
      "achromatopsia": {
        "hex": "959595",
        "rgb": { "r": 149, "g": 149, "b": 149 }
      }
    }
  },
  ...
}

Colorblind Types:

Protanopia: Red-blind (1% of males)
Deuteranopia: Green-blind (1% of males)
Tritanopia: Blue-blind (rare)
Achromatopsia: Complete color blindness (very rare)

GETCombined Request

curl "/api/v1/color/FF5733?accessibility=true&colorblind=true"

Include both accessibility and colorblind data in a single request for comprehensive color analysis.

06Field Reference

Field	Type	Description
color.hex	string	6-digit hex code (uppercase, no #)
color.rgb	object	RGB values (r, g, b) from 0-255
color.hsl	object	HSL values (h: 0-360, s/l: 0-100)
color.hsv	object	HSV values (h: 0-360, s/v: 0-100)
color.cmyk	object	CMYK values (0-100)
color.contrast	string	"light" or "dark" - recommended text color
isNamed	boolean	Whether this color has been named
data.name	string	The name given to this color
nearest.distance	number	Delta E (CIE76) perceptual distance (0 = identical)

07Additional Endpoints

GETHealth Check

curl "/api/health"

Check if the API is healthy and get basic system information.

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2024-12-21T...",
    "responseTime": "45ms",
    "services": {
      "database": "healthy"
    },
    "version": "1.0.0"
  }
}

GETStatistics

curl "/api/stats"

Get comprehensive statistics about named colors, partners, and recent activity.

{
  "success": true,
  "data": {
    "colors": {
      "named": 1250,
      "total": 16777216,
      "available": 16654766,
      "recent": 23
    },
    "partners": {
      "total": 15,
      "totalCredits": 500
    },
    "activity": {
      "recentTransactions": 5,
      "topOwners": [
        { "name": "John Doe", "count": 45 },
        { "name": "Jane Smith", "count": 32 }
      ]
    }
  }
}

GETAdvanced Search

curl "/api/search?q=blue&owner=john&sort=createdAt&limit=20"

Search named colors with advanced filters. Supports query, owner filtering, sorting, and pagination.

Query Parameters:

q - Search query (minimum 2 characters)
owner - Filter by color owner
sort - Sort by: name, owner, createdAt, hex (default: name)
order - Sort order: asc, desc (default: asc)
limit - Max results (default: 10, max: 50)

POSTBulk Availability Check

curl -X POST "/api/v1/colors/availability" \
  -H "Content-Type: application/json" \
  -d '{"hexes":["FF5733","3366CC","00FF00"]}'

Check availability for multiple colors in a single request. Maximum 100 colors per request.

{
  "success": true,
  "data": {
    "results": [
      {
        "hex": 16734003,
        "available": false,
        "name": "Sunset Orange",
        "owner": "John Doe"
      },
      {
        "hex": 3355492,
        "available": true
      }
    ],
    "summary": {
      "total": 3,
      "available": 1,
      "named": 2
    }
  }
}

GETBrand Colors

curl "/api/brands?q=spotify&limit=10"

Search official brand color palettes from 600+ companies. Get hex codes for Spotify, Google, Netflix, and more.

Query Parameters:

q - Search query (searches brand name)
limit - Max results (default: 50, max: 200)
offset - Skip N results for pagination

{
  "success": true,
  "data": {
    "brands": [
      {
        "id": "abc123",
        "name": "Spotify",
        "slug": "spotify",
        "colors": ["#1DB954", "#191414"],
        "brandUrl": "https://www.spotify.com/",
        "sourceUrl": "https://developer.spotify.com/design/"
      }
    ],
    "pagination": {
      "total": 691,
      "limit": 50,
      "offset": 0,
      "hasMore": true
    }
  }
}

08AI Agent Support (MCP)

OpenColors implements the Model Context Protocol (MCP), allowing AI agents like Claude Desktop to directly query our live database of 16.7 million colors.

MCP Endpoint

/api/mcp

Setup Instructions

For Claude Desktop (macOS)

Create or edit the config file:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "opencolors": {
      "command": "echo",
      "args": ["MCP server available at /api/mcp"]
    }
  }
}

Restart Claude Desktop after updating the config.

Test Connection

Test the MCP server directly:

# Create test script
cat > test-mcp.js << 'EOF'
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
const { StreamableHTTPClientTransport } = require('@modelcontextprotocol/sdk/client/streamableHttp.js');

async function test() {
  const transport = new StreamableHTTPClientTransport(new URL('/api/mcp'));
  const client = new Client({ name: 'test', version: '1.0.0' });
  await client.connect(transport);

  const tools = await client.listTools();
  console.log('✅ Connected! Available tools:', tools.tools.map(t => t.name));

  const result = await client.callTool({ name: 'search-colors', arguments: { query: 'blue' } });
  console.log('🔍 Search result:', JSON.parse(result.content[0].text).length, 'colors found');

  await client.close();
}
test();
EOF

# Run test
node test-mcp.js

Available Tools

search-colorsFind named colors by query string (case-insensitive)
get-recent-colorsList the 50 most recently named colors

Resources

color://{hex}Direct read access to color metadata by hex code

Example Usage in Claude

Once configured, you can ask Claude questions like:

• "What colors contain 'sunset' in their name?"

• "Show me the most recently named colors"

• "Tell me about the color FF5733"

09HTTP Status Codes

Status Code	Meaning	Description
200 OK	Success	Request completed successfully
400 Bad Request	Invalid Input	Invalid hex format, missing parameters, or malformed request
404 Not Found	Not Found	Endpoint does not exist
429 Too Many Requests	Rate Limited	Too many requests (currently not enforced)
500 Internal Server Error	Server Error	Unexpected server error occurred
503 Service Unavailable	Unavailable	Service temporarily unavailable (maintenance)

10Error Codes

Error Code	Description	Resolution
INVALID_HEX_FORMAT	Hex color format is invalid	Use 6-character hex without # (e.g., FF5733)
MISSING_PARAMETER	Required parameter is missing	Check the endpoint documentation for required parameters
INVALID_QUERY	Search query is too short or invalid	Minimum 2 characters required for search
LIMIT_EXCEEDED	Request exceeds maximum limit	Reduce the number of items in bulk request (max 100)
DATABASE_ERROR	Internal database error occurred	Retry the request or contact support if persistent

11Notes & Best Practices

✓ CORS Enabled

All endpoints support CORS with Access-Control-Allow-Origin: *. You can call this API from any domain without restrictions.

✓ Color Distance

The distance field uses Delta E (CIE76), a perceptual color difference metric. Lower values mean more similar colors. Generally: 0-1 = imperceptible,1-2 = slight, 2-10 = noticeable, 10+ = very different.

⚡ Rate Limits

Currently no rate limits are enforced. Please be reasonable with usage to keep the API free and available for everyone.

Best Practices:

Cache responses when possible to reduce redundant requests
Use bulk endpoints (like /api/v1/colors/availability) for checking multiple colors
Implement exponential backoff for retries on errors
Consider storing frequently accessed color data locally

💡 Performance Tips

Batch color lookups using the bulk availability endpoint
Only request optional parameters (accessibility, colorblind) when needed
Use ETags and conditional requests for caching (if you implement client-side caching)
Consider using a CDN or edge caching for static color data

🔒 Security

No API keys required. All endpoints are public and read-only. Always validate and sanitize color data on your server before using it in your application.