COLOURlovers API Documentation and Showcase

With the release of the COLOURlovers API, you can now access almost 1 million named colors and more than 325,000 color palettes for your creative projects and applications. Creating a theme editor and want to give your users some color theme options? Creating a visual project that ties keywords to colors? Who knows what amazingly creative stuff people will come up with.

Below are two showcase examples of the COLOURlovers API in action as well as the full API documentation. Happy API COLOURloving!

COLOURlovers API Usage Showcase

Desktop Color Search - AIR App

Desktop Color Search is an Adobe AIR app that runs on your desktop and allows you to search the entire COLOURlovers database for colors, palettes and patterns. You'll need to download the Adobe AIR runtime in order to run Desktop Color Search, you can use the link below to install AIR. (It works in both Windows and on Mac OS X) Special thanks to Levi McCallum at FutonMedia for coding the AIR app.

Download Desktop Color Finder | Download Adobe AIR

DEKAF LOVERS

A simple interface to COLOURlover's deep, deep palette library, it creates randomized compositions using rectangular geometry drawn by the Degrafa drawing library. Have some fun of your own color fun with Dekaf Lovers.

COLOURlovers API Documentation

License:

Attribution-Noncommercial-Share Alike - http://creativecommons.org/licenses/by-nc-sa/3.0/
If you would like to use the API in ways outside of this license please contact us for permission.

Colors:

Request URLs: [For Multiple Colors]
http://www.colourlovers.com/api/colors
http://www.colourlovers.com/api/colors/new
http://www.colourlovers.com/api/colors/top Parameters [Case-sensitve]: lover, hueRange, briRange, keywords, orderCol, sortBy, numResults, resultOffset
examples:
lover = COLOURlover
hueRange = 12,68 [values must be 0>value<359, and the left value must be less than the right value]
briRange = 2,88 [values must be 0>value<99, and the left value must be less than the right value]
keywords = search+term
orderCol = X [Where X can be: dateCreated, score, name, numVotes, numViews]
sortBy = X [Where X can be: ASC, DESC]
numResults = 20 [Number of results to return, maximum of 100. Default 20]
resultOffset = 5 [Result offset, for paging. Default 0] Requests with orderCol defined will override any /new or /top switch
Request URL: [For One Color]
http://www.colourlovers.com/api/color/1133EF - Where 1133EF is any 6 char hex value Parameters: N/A Example Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<colors>
	<color>
		<title><![CDATA[wet dirt]]></title>
		<userName><![CDATA[jessicabrown]]></userName>
		<numViews>0</numViews>
		<numVotes>0</numVotes>
		<numComments>0</numComments>
		<numHearts>0</numHearts>
		<rank>903853</rank>
		<dateCreated>2008-03-17 11:22:21</dateCreated>
		<hex>6B4106</hex>
		<rgb>
			<red>107</red>
			<green>65</green>
			<blue>6</blue>
		</rgb>
		<hsv>
			<hue>35</hue>
			<saturation>94</saturation>
			<value>42</value>
		</hsv>
		<description><![CDATA[]]></description>
		<url><![CDATA[http://www.colourlovers.com/color/6B4106/wet_dirt]]></url>
		<imageUrl><![CDATA[http://www.colourlovers.com/img/6B4106/100/100/wet_dirt.png]]></imageUrl>
		<apiUrl>http://www.colourlovers.com/api/color/6B4106</apiUrl>
	</color>
</colors>

Breakdown of API xml:

title	Title / Name of the color CDATA
userName	Username of the color's creator CDATA
numViews	Number of views this color has received
numVotes	Number of votes this color has received
numComments	Number of comments this color has received
numHearts	Number of hearts this color has
rank	This color's rank on COLOURlovers.com
dateCreated	Date this color was created
hex	This color's hex value
rgb	RGB breakdown of this color
red	Red value
green	Green value
blue	Blue value
hsv	HSV breakdown of this color
hue	Hue value
saturation	Saturation value
value	Value / Balance value
description	This color's description CDATA
url	This color's COLOURlovers.com URL CDATA
imageUrl	Link to a png version of this color CDATA
apiUrl	This color's COLOURlovers.com API URL CDATA

Palettes:

Request URLs: [For Multiple Palettes]
http://www.colourlovers.com/api/palettes
http://www.colourlovers.com/api/palettes/new
http://www.colourlovers.com/api/palettes/top Parameters [Case-sensitve]: lover, hueOption, hex, keywords, orderCol, sortBy, numResults, resultOffset
examples:
lover = COLOURlover
hueOption = yellow,orange,red [possible values: red, orange, yellow, green, aqua, blue, violet, fuchsia]
hueOption = yellow,orange
hueOption = yellow
hex = 00FF33
keywords = search+term
orderCol = X [Where X can be: dateCreated, score, name, numVotes, numViews]
sortBy = X [Where X can be: ASC, DESC]
numResults = 20 [Number of results to return, maximum of 100. Default 20]
resultOffset = 5 [Result offset, for paging. Default 0] Requests with orderCol defined will override any /new or /top switch
Request URL: [For One Palette]
http://www.colourlovers.com/api/palette/113451 - Where 113451 is a valid paletteID Parameters: N/A
Example Result:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<palettes>
	<palette>
		<title><![CDATA[be my boy]]></title>
		<userName><![CDATA[sinta schneider]]></userName>
		<numViews>1052</numViews>
		<numVotes>37</numVotes>
		<numComments>13</numComments>
		<numHearts>4.5</numHearts>
		<rank>1</rank>
		<dateCreated>2008-03-01 16:19:21</dateCreated>
		<colors>
			<hex>423238</hex>
			<hex>F5DE8C</hex>
			<hex>C8D197</hex>
			<hex>B3702D</hex>
			<hex>EB2138</hex>
		</colors>
		<description><![CDATA[]]></description>
		<url><![CDATA[http://www.colourlovers.com/palette/293826/be_my_boy]]></url>
		<imageUrl><![CDATA[http://www.colourlovers.com/paletteImg/423238/F5DE8C/C8D197/B3702D/EB2138/be_my_boy.png]></imageUrl>
		<apiUrl>http://www.colourlovers.com/api/palette/293826</apiUrl>
	</palette>
</palettes>

Breakdown of API xml:

title	Title / Name of the palette CDATA
userName	Username of the palette's creator CDATA
numViews	Number of views this palette has received
numVotes	Number of votes this palette has received
numComments	Number of comments this palette has received
numHearts	Number of palette this color has
rank	This palette's rank on COLOURlovers.com
dateCreated	Date this palette was created
colors	List of colors within this palette
hex	Hex value
hex	Hex value
[hex]	Hex value [may not be present]
[hex]	Hex value [may not be present]
[hex]	Hex value [may not be present]
description	This palette's description CDATA
url	This palette's COLOURlovers.com URL CDATA
imageUrl	Link to a png version of this palette CDATA
apiUrl	This palette's COLOURlovers.com API URL CDATA

Patterns:

Request URLs: [For Multiple Patterns]
http://www.colourlovers.com/api/patterns
http://www.colourlovers.com/api/patterns/new
http://www.colourlovers.com/api/patterns/top Parameters [Case-sensitve]: lover, hueOption, hex, keywords, orderCol, sortBy, numResults, resultOffset
examples:
lover = COLOURlover
hueOption = yellow,orange,red [possible values: red, orange, yellow, green, aqua, blue, violet, fuchsia]
hueOption = yellow,orange
hueOption = yellow
hex = 00FF33
keywords = search+term
orderCol = X [Where X can be: dateCreated, score, name, numVotes, numViews]
sortBy = X [Where X can be: ASC, DESC]
numResults = 20 [Number of results to return, maximum of 100. Default 20]
resultOffset = 5 [Result offset, for paging. Default 0] Requests with orderCol defined will override any /new or /top switch
Request URL: [For One Pattern]
http://www.colourlovers.com/api/pattern/1451 - Where 1451 is a valid patternID Parameters: N/A
Example Result:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<patterns>
	<pattern>
		<title><![CDATA[Tenderness.]]></title>
		<userName><![CDATA[not.an.am.person]]></userName>
		<numViews>617</numViews>
		<numVotes>32</numVotes>
		<numComments>14</numComments>
		<numHearts>4.5</numHearts>
		<rank>1</rank>
		<dateCreated>2008-03-01 06:43:38</dateCreated>
		<colors>
			<hex>C6C5AC</hex>
			<hex>CDB89F</hex>
			<hex>D4AA93</hex>
			<hex>B8E0C5</hex>
			<hex>BFD3B8</hex>
		</colors>
		<description><![CDATA[]]></description>
		<url><![CDATA[http://www.colourlovers.com/pattern/49471/Tenderness.]]></url>
		<imageUrl><![CDATA[http://colourlovers.com.s3.amazonaws.com/images/patterns/49/49471.png]></imageUrl>
		<apiUrl>http://www.colourlovers.com/api/pattern/49471</apiUrl>
	</pattern>
</patterns>

Breakdown of API xml:

title	Title / Name of the pattern CDATA
userName	Username of the pattern's creator CDATA
numViews	Number of views this pattern has received
numVotes	Number of votes this pattern has received
numComments	Number of comments this pattern has received
numHearts	Number of pattern this color has
rank	This pattern's rank on COLOURlovers.com
dateCreated	Date this pattern was created
colors	List of colors within this pattern
hex	Hex value
hex	Hex value
[hex]	Hex value [may not be present]
[hex]	Hex value [may not be present]
[hex]	Hex value [may not be present]
description	This pattern's description CDATA
url	This pattern's COLOURlovers.com URL CDATA
imageUrl	Link to a png version of this pattern CDATA
apiUrl	This pattern's COLOURlovers.com API URL CDATA

Lovers:

Request URLs: [For Multiple Lovers]
http://www.colourlovers.com/api/lovers
http://www.colourlovers.com/api/lovers/new
http://www.colourlovers.com/api/lovers/top Parameters [Case-sensitve]: orderCol, sortBy, numResults, resultOffset

examples:
orderCol = X [Where X can be: lastActive, name]
sortBy = X [Where X can be: ASC, DESC]
numResults = 20 [Number of results to return, maximum of 100. Default 20]
resultOffset = 5 [Result offset, for paging. Default 0]

Requests with orderCol defined will override any /new or /top switch
Request URL: [For One Lover]
http://www.colourlovers.com/api/lover/COLOURlover - Where COLOURlover is a valid COLOURlovers.com Username

Parameters [Case-sensitve]: comments
examples:
comments = 1 [will show last 10 comments for given lover] Example Result:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<lovers>
	<lover>
		<userName><![CDATA[electrikmonk]]></userName>
		<dateRegistered>2005-08-07 6:45:47</dateRegistered>
		<dateLastActive>2008-03-16 21:02:01</dateLastActive>
		<rating>554159</rating>
		<location><![CDATA[#FF0000stick, LA, US]]></location>
		<numColors>3,498</numColors>
		<numPalettes>2,775</numPalettes>
		<numPatterns>36</numPatterns>
		<numCommentsMade>7,201</numCommentsMade>
		<numLovers>710</numLovers>
		<numCommentsOnProfile>672</numCommentsOnProfile>
		Optional comments [Only returned when viewing one lover with the ?comments=1]
		<comments>
			<comment>
			<commentDate>2008-03-10 05:10:58</commentDate>
				<commentUserName><![CDATA[mashedpotato]]></commentUserName>
				<commentComments><![CDATA[you are so awesome. :x ]]></commentComments>
			</comment>
		</comments>
		<url><![CDATA[http://www.colourlovers.com/lover/electrikmonk]]></url>
		<apiUrl><![CDATA[http://www.colourlovers.com/api/lover/electrikmonk]]></apiUrl>
	</lover>
</lovers>

Breakdown of API xml:

userName	This lover's Username CDATA
dateRegistered	Date this lover registered with COLOURlovers.com
dateLastActive	Date this lover was last active on COLOURlovers.com
rating	This lover's rating
location	This lover's location
numColors	Number of colors this lover has made
numPalettes	Number of palettes this lover has made
numPatterns	Number of patterns this lover has made
numCommentsMade	Number of comments this lover has made
numLovers	Number of lovers [friends] this lover has
numCommentsOnProfile	Number of comments this lover has on their profile
Optional comments [Only returned when viewing one lover with the ?comments=1]
comments	Last 10 comments made on this lover's profile
comment	Individual comment
commentDate	Date the comment was made Format YYYY-MM-DD HH:MM:SS - times are CST/CDT
commentUserName	Commenter's COLOURlovers.com Username CDATA
commentComments	And finally, the comments! CDATA
url	This lovers's COLOURlovers.com URL CDATA
apiUrl	This lovers's COLOURlovers.com API URL CDATA

Example API code [PHP]:

<?php
	$curl = curl_init();
	curl_setopt($curl,CURLOPT_URL,"http://www.colourlovers.com/api/colors/new");
	curl_setopt($curl,CURLOPT_HEADER,false);
	curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
	$xml = curl_exec($curl);
	curl_close($curl);

	header("Content-Type: text/xml; charset=utf-8");
	echo $xml;
?>

 

PHP Wrapper to the API

phpColourLover PHP wrapper for the COLOURlovers API by gsmonk