COLOURlovers API Documentation and Showcase
Print this page
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:
If you would like to use the API in ways outside of this license please contact us for permission.
Colors:
http://www.colourlovers.com/api/colorshttp://www.colourlovers.com/api/colors/newhttp://www.colourlovers.com/api/colors/tophttp://www.colourlovers.com/api/colors/random [No parameters allowed]
Parameters [Case-sensitve]: lover, hueRange, briRange, keywords, keywordExact, orderCol, sortBy, numResults, resultOffset
examples:
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
keywordExact = X [Where
X can be 0 or 1 - performs an exact search for the keywords passed. Default 0]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]
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:
http://www.colourlovers.com/api/paletteshttp://www.colourlovers.com/api/palettes/newhttp://www.colourlovers.com/api/palettes/tophttp://www.colourlovers.com/api/palettes/random [No parameters allowed]
Parameters [Case-sensitve]: lover, hueOption, hex, keywords, keywordExact, orderCol, sortBy, numResults, resultOffset
examples:
hueOption = yellow,orange,red [possible values: red, orange, yellow, green, aqua, blue, violet, fuchsia]
hueOption = yellow,orange
hueOption = yellow
hex = 00FF33
keywords = search+term
keywordExact = X [Where
X can be 0 or 1 - performs an exact search for the keywords passed. Default 0]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]
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:
http://www.colourlovers.com/api/patternshttp://www.colourlovers.com/api/patterns/newhttp://www.colourlovers.com/api/patterns/tophttp://www.colourlovers.com/api/patterns/random [No parameters allowed]
Parameters [Case-sensitve]: lover, hueOption, hex, keywords, keywordExact, orderCol, sortBy, numResults, resultOffset
examples:
hueOption = yellow,orange,red [possible values: red, orange, yellow, green, aqua, blue, violet, fuchsia]
hueOption = yellow,orange
hueOption = yellow
hex = 00FF33
keywords = search+term
keywordExact = X [Where
X can be 0 or 1 - performs an exact search for the keywords passed. Default 0]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]
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:
http://www.colourlovers.com/api/lovershttp://www.colourlovers.com/api/lovers/newhttp://www.colourlovers.com/api/lovers/topParameters [Case-sensitve]: orderCol, sortBy, numResults, resultOffset
examples:
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:
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><
]]></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
COLOURlovers API
Copyright © 2008, COLOURlovers.com
All rights reserved.
Access to the services provided by this website and the COLOURlovers API and use of the information and services provided through the same, with or without modification, are permitted provided that the following conditions are met:
- Websites or software that use the information and services provided by this website and API must provide attribution credit to colourlovers.com.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of colourlovers.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission, apart from the required attribution above.
THIS WEBSITE AND THE COLOURlovers API IS PROVIDED BY COLOURLOVERS.COM “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL COLOURLOVERS.COM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32
Did you enjoy our post? Get our blog feed by 
Do you have something interesting and colorful you want to share with
0
