ColorTag API Documentation

Contents

Usage Sample

Usage Sample

Feel free to try ColorTag API as much as you like or start using it right now for free!

Overview

ColorTag is a powerful API for color detection. Taking an image file (or URL) as input ColorTag produces a list of text labels and hex RGB values that can be then used as tags for a certain image or item. The API can sort tags by relevance (recognizing colors of objects on the pictures, e.g. a dress, a car, etc.) or simply by weight in the image. First mode is perfect for e-commerce applications, allowing to automatically tag items with colors by simply providing a photo or a thumbnail and build a color tag cloud, so users are able to search items by color (e.g. red). Weight sorting mode can be useful for photos, wallpapers or other images without well-defined objects on them to analyze the palette in general. Text color labels can be assigned with different precision (just basic colors, W3C-compatible colors, precise colors, etc.). Free usage plan available!

Use Cases

ColorTag API can perform color segmentation and histogram analysis to provide descriptive color statistics for an image. It can be useful color-processing utility in the following cases:

Endpoints

Please note: you need a Mashape account to consume the API. Please visit ColorTag on Mashape to learn more.

ColorTag API supports two endpoints that differ only in the way of passing the image:

http://apicloud-colortag.p.mashape.com/tag-url.json

HTTP Method: GET

Parameters:

url – URL of the image you wish to analyze and find visually unique colors in.

palette (optional) – Defines the palette used to assign text labels. Default value is ‘simple’. For information on supported palettes please refer to the corresponding section of this documentation.

sort (optional) – Defines the way tags are sorted. Default is ‘relevance’. Sorting by relevance is best for determining object’s primary color, so the first tag is likely to be what you need. Another supported value is ‘weight’ – simply sort output tags by their weight in the image – best for determining the overall palette of the image.


http://apicloud-colortag.p.mashape.com/tag-file.json

HTTP Method: POST

Parameters:

image – Image you wish to analyze as uploaded file.

palette (optional) – Defines the palette used to assign text labels. Default value is ‘simple’. For information on supported palettes please refer to the corresponding section of this documentation.

sort (optional) – Defines the way tags are sorted. Default is ‘relevance’. Sorting by relevance is best for determining object’s main color, so the first tag is likely to be what you need. Another supported value is ‘weight’ – simply sort output tags by their weight in the image – best for determining the overall palette of the image.

Image Restrictions

Both endpoints have the same source image restrictions:

Supported formats: JPEG, PNG and GIF

Resolution: up to 8192×8192

File size: up to 20 MBytes


Please note: when using image URL the 'Content-Type' header should be set correctly by the Web-server (as well as the 'Content-Length').

Palettes

Palette defines a set of labels that can be assigned to the image. Palette can be specified via the ‘palette’ parameter. The table below contains a list of supported palettes and labels they contain (the name column corresponds to values of the ‘palette’ parameter).


Name Description Labels
simple This is the default palette (would be used if ‘palette’ parameter is omitted). It includes the most general colors (spectrum colors and few other). Red, Orange, Yellow, Green, Cyan, Blue, Purple, Pink, Beige, Brown, White, Gray, Black
w3c This palette contains W3C-compliant colors (can be used in HTML and CSS). AliceBlue, AntiqueWhite, Aquamarine, Azure, Beige, Bisque, Black, BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, CadetBlue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crimson, Cyan, DarkBlue, DarkCyan, DarkGoldenrod, DarkGray, DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange, DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, DarkSlateBlue, DarkSlateGray, DarkTurquoise, DarkViolet, DeepPink, DeepSkyBlue, DimGray, DodgerBlue, FireBrick, FloralWhite, ForestGreen, Gainsboro, GhostWhite, Gold, Goldenrod, Gray, Green, GreenYellow, Honeydew, HotPink, IndianRed, Indigo, Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon, LightBlue, LightCoral, LightCyan, LightGoldenrodYellow, LightGreen, LightGray, LightPink, LightSalmon, LightSeaGreen, LightSkyBlue, LightSlateGray, LightSteelBlue, LightYellow, Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquamarine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, MediumSlateBlue, MediumSpringGreen, MediumTurquoise, MediumVioletRed, MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy, OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGoldenrod, PaleGreen, PaleTurquoise, PaleVioletRed, PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, Red, RosyBrown, RoyalBlue, SaddleBrown, Salmon, SandyBrown, SeaGreen, Seashell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen
precise This palette contains about 1500 color names and can be used to precisely identify colors and tones. This palette contains too many colors to list here. If you need the complete list feel free to contact us.

Sorting

The ‘sort’ parameter specifies how resulting tags are sorted. Currently we support two sorting modes: based on relevance (takes many factors into account: color weight, image composition, background detection, etc.) and based on color weight (simply counts how many pixels with that color are there in the image). Relevance-based sorting is perfect for determining colors of objects (e.g. a dress, a car, a fruit, etc.) and the first tag is likely to be a color you need (e.g. green would be the first for a green dress). Weight-based sorting can be useful for general image analysis: the most used color would be the first one and so on. As mentioned before, sorting mode is controlled by the ‘sort’ parameter. Specify ‘relevance’ for relevance-based sorting (or simply omit the parameter as ‘relevance’ is the default value) or ‘weight’ for weight-based sorting.

Response

Both endpoints return the same response (with HTTP code 200) which is a JSON object of the following structure:

{
  "tags" : [
    {
      "label" : "Green",
      "color" : "#2A5D24"
    },
    {
      "label" : "Beige",
      "color" : "#A99670"
    },
    {
      "label" : "Gray",
      "color" : "#282523"
    },
    {
      "label" : "Brown",
      "color" : "#523E2D"
    }
  ]
}
                

The response object contains the "tags" field which is an array of tags. Each tag consists of a text label and a hex RGB value. Text label is generated according to the palette specified. RGB hex value is the average color (within the image) corresponding to the label. Text labels can be used as tags for items (photos, images, etc.), while RGB values can visually represent colors. For example, RGB color for the “Green” label tells us what kind of green it is (here it’s a dark shade of green). Tags in the list are sorted either by relevance or by weight (according to the sort method chosen). The first tag is the most relevant (or just the most occurring one if weight-based sorting is used).

Please note: even for precise palette RGB values are not exact colors and may differ depending on the image (as for the “Green” label there are many variations of green).

Please note: API currently returns top 20 tags, that should be more than enough for all use cases. However, feel free to inform us if you need more.

Errors

Errors can be identified by HTTP response codes (codes other than 200 should be considered an unsuccessful call). The following HTTP response codes can be returned by the API:

400 – Indicates bad request (invalid parameter values, URL not found, image size is too large, etc.)

500 – Indicates internal API error. This code, however, is rare and we monitor all the API logs to fix issues as soon as possible. However, if this error persists, please contact us.

Please note: you will not be charged for unsuccessful calls - only successful calls count.

Getting Started

First of all, you may wish to try a demo. Using ColorTag API from your application is pretty simple: just visit ColorTag on Mashape and subscribe a pricing plan you need (including a free one). After that you can perform API calls from the test console, try cURL examples, download a client library for a language of your choice or simply consume the API in a plain REST.