POST search

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

Resource URL

https://mobileengine.tineye.com/<company>/rest/search/

Performance

The MobileEngine API can perform four simultaneous search or comparison operations combined. Any extra requests submitted will be queued up for processing as slots become available. Doing more than four at a time would actually reduce 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 send a number of simultaneous URL-based requests. 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.

Checking for flips nearly doubles the time taken to perform a search; set check_horizontal_flip to false for much faster searching.

Image limitations

  • Image size: For optimal performance, images given by an image or url parameter should be 300px 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 MobileEngine server. It would be faster to resize this image to be 450x300 and then send it. Smaller images may work, and need not be scaled up.
  • Image content: Some images may not contain enough detail to be searched for effectively. For example, images that are extremely small or contain only a single color will return an error.
  • Image format: Accepted formats are JPEG, PNG, GIF (non-animated), BMP, and TIFF files.

Parameters

In addition to the Common parameters there are:

Key Description
image The image file object that will be used to search against the collection. This is referred to as the query image. Required if filepath or url has not been specified.
filepath The collection path to the image file that will be used to search against the collection. This is referred to as the query image. Required if image or url has not been specified.
url The URL of the image file that will be used to search against the collection. This is referred to as the query image. Required if image or filepath has not been specified.
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.
check_horizontal_flip (optional) Whether the search incorporates checking for horizontal flips, defaults to false.
generate_overlay (optional) Whether an overlay URL will be generated and returned, defaults to false.

Response

Key Description
score How closely the image matches the query image.
filepath The matching image’s file path.
match_percent How much the images match each other, as a percentage.
query_overlap_percent How much of the query image overlaps the matching image, as a percentage.
target_overlap_percent How much of the match image overlaps the query image, as a percentage.
overlay A URL pointing to the overlay for this search. Returned when generate_overlay parameter is set to true.

Request example

Image

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

Filepath

curl https://mobileengine.tineye.com/<company>/rest/search/         \
     -F "filepath=path/folder/query.jpg"

URL

curl https://mobileengine.tineye.com/<company>/rest/search/         \
     -F "url=http://example.com/query.jpg"

Response example

JSON

{
    "status": "ok",
    "error": [],
    "method": "search",
    "result": [
        {
            "match_percent": 100,
            "score": 100,
            "target_overlap_percent": 99.98,
            "query_overlap_percent": 100,
            "filepath": "path/folder/match1.png"
        },
        {
            "match_percent": 17.56,
            "score": 9.8,
            "target_overlap_percent": 80.48,
            "query_overlap_percent": 77.02,
            "filepath": "path/folder/match2.png"
        }
    ]
}

JSON (with generate_overlay)

{
    "status": "ok",
    "error": [],
    "method": "search",
    "result": [
        {
            "match_percent": 100,
            "score": 100,
            "target_overlap_percent": 99.98,
            "overlay": "overlay/?query=query.jpg&target=path/folder/match1.png&m21=0.000107246&m22=0.999991&m23=-0.00271503&m11=0.999991&m13=0.0154761&m12=-0.000107246",
            "query_overlap_percent": 100,
            "filepath": "path/folder/match1.png"
        },
        {
            "match_percent": 17.56,
            "score": 9.8,
            "target_overlap_percent": 80.48,
            "overlay": "overlay/?query=query.jpg&target=path/folder/match2.png&m21=-0.0995005&m22=1.04527&m23=140.846&m11=1.04527&m13=-41.0315&m12=0.0995005",
            "query_overlap_percent": 77.02,
            "filepath": "path/folder/match2.png"
        }
    ]
}

XML

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>search</method>
    <result>
        <item>
            <filepath>path/folder/match1.png</filepath>
            <match_percent>100.0</match_percent>
            <query_overlap_percent>100.0</query_overlap_percent>
            <score>100.0</score>
            <target_overlap_percent>99.98</target_overlap_percent>
        </item>
        <item>
            <filepath>path/folder/match2.png</filepath>
            <match_percent>17.56</match_percent>
            <query_overlap_percent>77.04</query_overlap_percent>
            <score>9.80</score>
            <target_overlap_percent>80.48</target_overlap_percent>
        </item>
    </result>
    <status>ok</status>
</data>

XML (with generate_overlay)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>search</method>
    <result>
        <item>
            <filepath>path/folder/match1.png</filepath>
            <match_percent>100.0</match_percent>
            <overlay>overlay/?query=query.jpg&amp;target=path/folder/match1.png&amp;m21=0.000107246&amp;m22=0.999991&amp;m23=-0.00271503&amp;m11=0.999991&amp;m13=0.0154761&amp;m12=-0.000107246</overlay>
            <query_overlap_percent>100.0</query_overlap_percent>
            <score>100.0</score>
            <target_overlap_percent>99.98</target_overlap_percent>
        </item>
        <item>
            <filepath>path/folder/match2.png</filepath>
            <match_percent>17.56</match_percent>
            <overlay>overlay/?query=query.jpg&amp;target=path/folder/match2.png&amp;m21=-0.0995005&amp;m22=1.04527&amp;m23=140.846&amp;m11=1.04527&amp;m13=-41.0315&amp;m12=0.0995005</overlay>
            <query_overlap_percent>77.04</query_overlap_percent>
            <score>9.80</score>
            <target_overlap_percent>80.48</target_overlap_percent>
        </item>
    </result>
    <status>ok</status>
</data>