ColorOf API Version 1

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.

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:

Unauthenticated API Calls

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.