POST color_search¶

Resource URL
Performance
Image limitations
Parameters
Request examples
Response examples

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.

When a set of colors are used for searching, one of the query colors can be a Wildcard color.

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/

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 600px in size in the smallest dimension. For example, 1200x800 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 900x600 and then send it. Smaller images may work, and need not be scaled up.
Image format: Accepted formats are JPEG, PNG, WEBP, AVIF, GIF, BMP and TIFF files. Animated images are not supported.

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 false.
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 false.
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 RGB format (255,255,255), hex format (ffffff) or as a wildcard (‘wildcard’).
…	…
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).
name_filter (optional)	Return only matches whose names match this filter (see Name Filtering for details).
path_filter (optional)	Return only matches whose paths match this filter (see Name Filtering for details).
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 0 indicates no limit.

Request examples ¶

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"

Colors (with a wildcard color)¶

curl https://multicolorengine.tineye.com/<company>/rest/color_search/    \
     -F "colors[0]=3F6BB9"                                               \
     -F "colors[1]=210,105,180"                                          \
     -F "colors[2]=wildcard"                                             \
     -F "weights[0]=25"                                                  \
     -F "weights[1]=20"                                                  \
     -F "weights[2]=55"

Response examples ¶

JSON (no metadata)¶

{
    "method": "color_search",
    "status": "ok",
    "error": [],
    "query_image": {
        "filepath": "query.jpg"
    },
    "result": [
        {
            "score": 97.2,
            "filepath": "path/folder/2.jpg"
        },
        {
            "score": 94.5,
            "filepath": "path/folder/1.jpg"
        }
    ],
    "stats": {
        "total_results": 2,
        "total_filtered_results": 2,
        "total_returned_results": 2,
        "time_resize": 42.47,
        "time_search": 100.88,
        "time_total": 144.2
    }
}

JSON (with metadata)¶

{
    "method": "color_search",
    "status": "ok",
    "error": [],
    "query_image": {
        "filepath": "path/folder/query.jpg"
    },
    "result": [
        {
            "score_metadata": 3.0,
            "metadata": {
                "id": "67890",
                "image_id": "dd8d-6dc8-bf3f"
            },
            "filepath": "path/folder/2.jpg"
        },
        {
            "score_metadata": 3.0,
            "metadata": {
                "id": "12345",
                "image_id": "db9561-7cecb6"
            },
            "filepath": "path/folder/1.jpg"
        }
    ],
    "stats": {
        "total_results": 2,
        "total_filtered_results": 2,
        "total_returned_results": 2,
        "time_download": 151.01,
        "time_resize": 76.25,
        "time_search": 129.71,
        "time_total": 358.12
    }
}

XML (no metadata)¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>color_search</method>
    <status>ok</status>
    <error/>
    <query_image>
        <filepath>query.jpg</filepath>
    </query_image>
    <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>
    <stats>
        <total_results>2</total_results>
        <total_filtered_results>2</total_filtered_results>
        <total_returned_results>2</total_returned_results>
        <time_resize>42.47</time_resize>
        <time_search>100.88</time_search>
        <time_total>144.2</time_total>
    </stats>
</data>

XML (with metadata)¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>color_search</method>
    <status>ok</status>
    <error/>
    <query_image>
        <filepath>path/folder/query.jpg</filepath>
    </query_image>
    <result>
        <item>
            <filepath>path/folder/2.jpg</filepath>
            <metadata>
                <id>67890</id>
                <image_id>dd8d-6dc8-bf3f</image_id>
            </metadata>
            <score_metadata>3.0</score_metadata>
        </item>
        <item>
            <filepath>path/folder/1.jpg</filepath>
            <metadata>
                <id>12345</id>
                <image_id>db9561-7cecb6</image_id>
            </metadata>
            <score_metadata>3.0</score_metadata>
        </item>
    </result>
    <stats>
        <total_results>2</total_results>
        <total_filtered_results>2</total_filtered_results>
        <total_returned_results>2</total_returned_results>
        <time_download>151.01</time_download>
        <time_resize>76.25</time_resize>
        <time_search>129.71</time_search>
        <time_total>358.12</time_total>
    </stats>
</data>

Developers