|  Login
 
 

Welcome to the ColorOf API

That’s right you are in the html view of the API right now. You are probably here because you want to implement color search. The goal of this documentation is to make that task easier. This site is the API but also live documentation on how it works and a great place to go for troubleshooting. Implementing color search is a two step process. The first step is to have us index all your color things by color. The second step is for you to write a great front end to this API so your users can discover your things by color.

 
 

In the ColorOf API there are the following assets:

ColorOf API Assets Description
Colors A color is the hexadecimal representation of color in the rgb color space.
Swatches A swatch is snippet of colors from a single thing associated with the metadata for that thing.
Palettes (coming soon) A palette is a collection of colors with a palette type. Palette types include arrangements such as coordinating, analogous, “look great together” and “perfectly mismatched”.
 
 

In order for ColorOf to index your things by color you need to publish the data we need for the swatch creation process. You will need to create an account to publish. If you want to automate (POST /swatches) publishing via this API you will need a paid for ColorOf Pro account. We also offer a free solution for publishing with the pub1 swatch creation tool. Search request queries are always free and open.

  • Create an Account
  • For a ColorOf Pro account please call (844) COLOR-OF
 
 
  Free Please Call
Max calls/hr 150 600 1200 3600 Unlimited
Max Swatches* 500 10000 50000 100000 Unlimited
Post API No

* This is the maximum number of swatches we will search through to find a match. We will search the latest publish up to the max. You can publish an unlimited number of swatches.

 
 

Authentication (ColorOf Pro)

Some methods of the ColorOf API require authentication to access them. In order to authenticate with our API you need an API Key and API Secret. To see your API Key and Secret login to your ColorOf Pro account and navigate to API Tokens. Once you have your API Key and API Secret you can start signing your ColorOf API requests that require authentication. To sign a request you must format the URL you are requesting access to in a specific manner and then encrypted that formatted URL with your API Secret as the key using Rijndael 256 CBC encryption. In this chart you will find an example to help clarify the encryption formula.

 
 
Variable Name Description Example Value
ORIG_URL ColorOf URL you are requesting http://www.colorof.com/swatches
API_KEY Your API Key ZjRhZTQ2MDJmMmY0YWE1MDhkMjMwOWMwMmMyMzAxMTFkYjdjNzliZg==
API_SECRET Your API Secret ZTNiNDUwYTZhNTM1MzYyMmFhYTJkNjVIMjlmZjk4ZWY=
REQ_TS Timestamp you are sending the request in milliseconds 1388577600000
VERIFY_URL ORIG_URL + “&” + REQ_TS http://www.colorof.com/swatches&1388577600000
ENCRYPT_IV 32 random bytes as an initialization vector for AES 256 CBC {RAW DATA}
ENCRYPT_TOKEN AES_256_CBC(key = base64decode(API_SECRET), data = VERIFY_URL, iv = ENCRYPT_IV) {RAW DATA}
VERIFY_TOKEN base64encode(ENCRYPT_IV+ ENCRYPT_TOKEN) YWUgNDEgNjYgYWYgYTUgNzggZjYgZGIgNDEgZGQgYjMgMTkgZTggNjkgNzEgZjkgDQoNCg==
SIGNED_URL ORIG_URL + “?” or “&” + “ak=” + API_KEY + “&av=” + VERIFY_TOKEN http://www.colorof.com/swatches?ak= ZjRhZTQ2MDJmMmY0YWE1MDhkMjMwOWMwMmMyMzAxMTFkYjdjNzliZg==&av= YWUgNDEgNjYgYWYgYTUgNzggZjYgZGIgNDEgZGQgYjMgMTkgZTggNjkgNzEgZjkgDQoNCg==

The final request you make into ColorOf will be the SIGNED_URL. Based on the data in the signed URL we can verify that your account has proper permissions to access the requested resource. If you do not generate and make the request using the signed URL quickly enough the API may deny your request. If you use a timestamp for REQ_TS in any time zone other than GMT your request may also be denied. It is important that your server’s clock is accurate. We highly recommended that the system clock you are requesting your ColorOf resource from is synced with an NTP server for more information about NTP visit (http://www.pool.ntp.org).

 
 

Authenticated API Calls

The following API calls require authentication to access them:

Swatches

POST /swatches
Creates a new swatch.

Parameter Description Example
name Swatch Name (Often the product name) Men’s Wrinkle Free Cotton Dress Shirt
desc Description of Swatch Our wrinkle free cotton dress shirts are guaranteed to make you look great.
link URL where item can be found or purchased. Usually a product page. http://www.example.com/product/page
image_link URL of product image. Usually a full product photo. Sometimes shown on a model. http://www.example.com/product/image.jpg
image_link2 URL of product swatch image such as a snippet of cloth showing color detail. This should be set to image_link if there is no alternate product photo. We highly recommend using a swatch image. http://www.example.com/product/swatch.jpg
uid Product Identification Number or SKU #123456
gravity This is important when you don’t provide a swatch image it hints at generally where in the image to look for the target colors. Can be one of the following values: NorthWest, North, NorthEast, West, Center, East, SouthWest, South, or SouthEast NorthWest

PUT /swatches{swatch_id}
Update swatch with id of swatch_id

Parameter Description Example
name Swatch Name (Often the product name) Men’s Wrinkle Free Cotton Dress Shirt
desc Description of Swatch Our wrinkle free cotton dress shirts are guaranteed to make you look great.
link URL where item can be found or purchased. Usually a product page. http://www.example.com/product/page
 
 

GET /swatches/{swatch_id}
Get the details of a swatch as JSON
Example response:


{
    "colors": [
        {
            "name": null,
            "color_names_id": null,
            "color_id": "13444923",
            "hexcode": "cd273a",
            "hexcode_name": null,
            "swatch_colors_id": "1436670",
            "color_percentage": "0.262395",
            "closest_named_color": {
                "level2": "red",
                "id": 882,
                "level1": "red",
                "name": "Unnamed #C02040",
                "dist": 15.937377450509,
                "color_hexcode": "c02040",
                "color_rgb": "192,32,64",
                "color_id": 12591169
            }
        }
    ],
    "tags": [
        {
            "id": "65497",
            "name": "ColorOf",
            "ele_id": "2411467"
        }
    ],
    "info": {
        "id": "603830",
        "user_id": "31",
        "name": "Bougainvillea Glabra",
        "desc": "Great color capture of common keyword requests found on a ColorOf index of images",
        "image_link": "http://static.example.com/705/020114_4123fb5c9.jpg",
        "swatch_url": "http://static.example.com/705/020114_4123fb5c9.jpg",
        "link": "http://www.example.com/photos/johnny@N02/68987251/",
        "link_clicks": "0",
        "uid": "6898637251",
        "rating": "0",
        "views": "0",
        "commentable": "1",
        "private": "0",
        "status": "0",
        "created": "2013-01-22 04:34:57",
        "ordered": "1",
        "deleted": "0",
        "featured": "0",
        "edit": null,
        "editor": null,
        "width": "500"
    },
    "user": {
        "id": "31",
        "username": "Johnny",
        "display_name": "Johnny"
    },
    "session_username": -1,
    "session_display_name": -1,
    "session_user_id": -1,
    "session_role": -1
}

DELETE /swatches/{swatch_id}
Deletes a swatch with id of swatch_id

Unauthenticated API Calls

The following API calls require authentication to access them:

Search
GET /search

Parameter Description Example
format Format of your response: this can be json or xml This should always be set to json as it is the most tested format. json
query Textual query to search for shirt
hex RGB hex code to search for ffffff
accuracy Percentage of fuzziness to search for around the hex color. 4 is generally a good percentage to start with. Results are ordered by distance away from requested color so closest matching colors are returned first. 4
user_id User account to search for swatches under. If you just want to search for your own products put your own user_id in here. 22
search_by Search method. Either swatch or palette. Swatch is currently fully supported, palette is not at this time. swatch

Example url (should always include &format=json when integrating):
http://api.colorof.com/search?url=&query=&query=Flower&hex=%23e29f11&accuracy=10&user_id=3&cname=&search_by=swatch
Example response:


{
    "palettes": [],
    "swatches": [
        {
            "desc": "Our slim fit short sleeve sport shirt are great for summer activities",
            "swatch_url": "http://static.example.com/PI4/0/1080/2310064_full.jpg",
            "link": "http://example.com/products/mens/shirt/2310064",
            "featured": "false",
            "image_link": "http://static.example.com/PI4/0/1080/2310064_swatch.jpg",
            "deleted": "false",
            "id": "329513",
            "created": "2012-06-13T14:55:13Z",
            "name": "Short Sport Shirt",
            "user_id": "1834",
            "user_display_name": "example.com",
            "score": 2.6271362,
            "colors": [
                {
                    "id": 1406029,
                    "hexcode": "15744c",
                    "color_dist": 6.7082039324994,
                    "color_percentage": "0.536752",
                    "swatch_color_id": 755760,
                    "color_closest": true
                },
                {
                    "id": 1607254,
                    "hexcode": "188655",
                    "color_dist": 20.420577856662,
                    "color_percentage": "0.340395",
                    "swatch_color_id": 755761
                }
            ],
            "tags": [
                {
                    "id": "26",
                    "name": "Shirts"
                }
            ]
        },
        {
            "desc": "Our Short Sleeve Cotton Performance T-Shirt",
            "swatch_url": " http://static.example.com/PI4/0/1080/2310065_full.jpg",
            "link": " http://example.com/products/mens/shirt/2310065",
            "featured": "false",
            "image_link": " http://static.example.com/PI4/0/1080/2310064_swatch.jpg",
            "deleted": "false",
            "id": "372852",
            "created": "2012-06-14T03:20:06Z",
            "name": "Short Sleeve Cotton T-Shirt",
            "user_id": "1834",
            "user_display_name": " example.com ",
            "score": 2.5152595,
            "colors": [
                {
                    "id": 1274446,
                    "hexcode": "13724d",
                    "color_dist": 8.4852813742386,
                    "color_percentage": "0.597141",
                    "swatch_color_id": 862703,
                    "color_closest": true
                },
                {
                    "id": 2261598,
                    "hexcode": "22825d",
                    "color_dist": 28.442925306656,
                    "color_percentage": "0.182614",
                    "swatch_color_id": 862702
                }
            ],
            "tags": [
                {
                    "id": "26",
                    "name": "Shirts"
                }
            ]
        }
    ]
}