POST color_search

Given an image, the path of a file already in your collection, or a set of colors, run a color search against your collection and return any matches, with their corresponding scores.

You can include metadata in any of those color-based searches, or you can search by metadata alone.

Resource URL

https://multicolorengine.tineye.com/<company>/rest/color_search/

Performance

The MulticolorEngine API can perform four simultaneous searches. Any extra requests submitted will be queued up for processing as slots become available. Doing more than four at a time would actually increase average response time, since the processes are CPU bound.

If you are searching by image or filepath then operations are performed in the order in which they are received. If you are searching by URL then the images are downloaded before the operations go into the queue. Thus, it may be advantageous to allow a number of simultaneous URL-based searches. You should experiment with the effect of different numbers, since results will vary with things like download speed and network contention.

For maximum performance images should be pre-scaled, as described under Image Limitations below. Thus, in some cases where you could use URLs, it may be better to do the download yourself, scale the image, and send it in the request.

Image limitations

  • Image size: For optimal performance, images given by an image or url parameter should be 200px in size in the smallest dimension. For example, 600x400 pixels is larger than required and it will take longer to transfer this file to your MulticolorEngine server. It would be faster to resize this image to be 300x200 and then send it. Smaller images may work, and need not be scaled up.
  • Image format: Accepted formats are JPEG, PNG, GIF (non-animated), BMP, and TIFF files.

Parameters

A color search is given by one of image, filepath, or url, or a set of colors[n]. metadata is always optional, and you may search by metadata alone by not specfiying an image or colors with it.

In addition to the Common parameters there are:

Key Description
image The image file object that will be used to search against the collection. The colors from the image will be extracted and used to search against the collection.
filepath The path to an image file in the collection that will be used to search against the collection.
url The URL of the image file that will be used to search against the collection.
ignore_background (optional) Whether to detect and ignore the background region of the image file, can be either true or false, defaults to true.
ignore_interior_background (optional) Whether to detect and ignore regions that have the same color as the background region but are surrounded by one or more non background regions, can be either true or false, defaults to true.
metadata (optional) The metadata to be used for additional filtering.
return_metadata (optional) The metadata to be returned with each match.
sort_metadata (optional) Whether the search results are sorted by metadata score, can be either true or false, defaults to false which means that the results are sorted by the match score.
colors[0] A color which you want to use as input for the color search. Required if image, url, or filepath has not been specified for a color-based search. The maximum number of colors that can be specified for a search is 5. Can be entered in either RGB format (255,255,255) or hex format (ffffff).
... ...
colors[n] (optional) ...
weights[0] (optional but required for all colors if specified) A weight for the first color, should be between 1 and 100, and add up to 100.
... ...
weights[n] (optional) ...
min_score (optional) The minimum score that should be returned, defaults to 0. Should be between 0 and 100 (inclusive).
offset (optional) The offset of results from the start, defaults to 0.
limit (optional) The maximum number of matches that should be returned, defaults to 10. A value of -1 indicates no limit.

Request example

Image

curl https://multicolorengine.tineye.com/<company>/rest/color_search/     \
     -F "image=@query.jpg"

Filepath (with metadata filtering)

curl https://multicolorengine.tineye.com/<company>/rest/color_search/    \
     -F "filepath=path/folder/query.jpg"                                 \
     -F "metadata='{\"keywords\": \"whale\"}'"

Filepath (with return_metadata and sorting)

curl https://multicolorengine.tineye.com/<company>/rest/color_search/    \
     -F "filepath=path/folder/query.jpg"                                 \
     -F "metadata='{\"keywords\": \"whale\"}'"                           \
     -F "return_metadata='{\"id\": {\"sort\": \"desc\", \"\": null}}'"

URL

curl https://multicolorengine.tineye.com/<company>/rest/color_search/    \
     -F "url=http://example.com/query.jpg"                               \
     -F "ignore_background=true"                                         \
     -F "ignore_interior_background=false"

Colors

curl https://multicolorengine.tineye.com/<company>/rest/color_search/    \
     -F "colors[0]=255,112,223"                                          \
     -F "colors[1]=DF4F23"                                               \
     -F "weights[0]=70"                                                  \
     -F "weights[1]=30"

Response example

JSON (no metadata)

{
    "count": "2",
    "status": "ok",
    "error": [],
    "method": "color_search",
    "result": [
        {
            "score": 97.2,
            "filepath": "path/folder/2.jpg"
        },
        {
            "score": 94.5,
            "filepath": "path/folder/1.jpg"
        }
    ]
}

JSON (with metadata)

{
    "count": "2",
    "status": "ok",
    "error": [],
    "method": "color_search",
    "result": [
        {
            "metadata-score": 3.0,
            "metadata": {
                "id": "67890"
            },
            "filepath": "path/folder/2.jpg"
        },
        {
            "metadata-score": 3.0,
            "metadata": {
                "id": "12345"
            },
            "filepath": "path/folder/1.jpg"
        }
    ]
}

XML (no metadata)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <count>2</count>
    <error/>
    <method>color_search</method>
    <result>
        <item>
            <filepath>path/folder/2.jpg</filepath>
            <score>97.20</score>
        </item>
        <item>
            <filepath>path/folder/1.jpg</filepath>
            <score>94.50</score>
        </item>
    </result>
    <status>ok</status>
</data>

XML (with metadata)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <count>2</count>
    <error/>
    <method>color_search</method>
    <result>
        <item>
            <filepath>path/folder/2.jpg</filepath>
            <metadata>
                <id>67890</id>
            </metadata>
            <metadata-score>3.0</metadata_score>
        </item>
        <item>
            <filepath>path/folder/1.jpg</filepath>
            <metadata>
                <id>12345</id>
            </metadata>
            <metadata-score>3.0</metadata_score>
        </item>
    </result>
    <status>ok</status>
</data>