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 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 MobileEngine 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 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, WEBP, AVIF, GIF, BMP and TIFF files. Animated images are not supported.
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. |
check_horizontal_flip (optional) |
Whether the search incorporates checking for horizontal flips, defaults to false. |
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. |
generate_overlay (optional) |
Whether an overlay URL will be generated and returned, defaults to false. |
Response¶
Key |
Description |
|---|---|
filepath |
The collection image’s file path. |
score |
How closely the query image matches the collection image. |
match_percent |
How much of the query image’s fingerprint overlaps the collection image’s fingerprint, as a percentage. |
query_overlap_percent |
How much of the query image overlaps the collection image, as a percentage. |
target_overlap_percent |
How much of the collection image overlaps the query image, as a percentage. |
query_match_rect |
Location of the matching area in the query image. |
target_match_rect |
Location of the matching area in the collection image. |
overlay |
A URL pointing to the overlay for this search. Returned when generate_overlay parameter is set to true. |
The locations returned by MobileEngine will always refer to the image used for comparison and are provided as bounding boxes. These bounding boxes will be described using four percentage values (left, right, top, bottom) computed relative to image’s dimensions.
Please note that if your image has solid color borders, those might be cropped out by MobileEngine. In that case the locations returned will only refer to the cropped version of the image.
Request examples¶
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 examples¶
JSON¶
{
"method": "search",
"status": "ok",
"error": [],
"query_image": {
"filepath": "query.jpg"
},
"result": [
{
"filepath": "path/folder/match1.png",
"score": 100,
"match_percent": 100,
"query_overlap_percent": 100,
"target_overlap_percent": 99.98,
"metadata": {
"image_id": "dd8d-6dc8-bf3f"
},
"query_match_rect": {
"left": 2.8,
"right": 92.67,
"top": 12.44,
"bottom": 83.78
},
"target_match_rect": {
"left": 10.36,
"right": 98.5,
"top": 14.56,
"bottom": 87.89
}
},
{
"filepath": "path/folder/match2.png",
"score": 9.8,
"match_percent": 17.56,
"query_overlap_percent": 77.02,
"target_overlap_percent": 80.48,
"metadata": {
"image_id": "db9561-7cecb6"
},
"query_match_rect": {
"left": 11.4,
"right": 61.7,
"top": 32.65,
"bottom": 73.8
},
"target_match_rect": {
"left": 33.1,
"right": 69.45,
"top": 27.62,
"bottom": 89.63
}
}
],
"stats": {
"total_results": 2,
"total_filtered_results": 2,
"total_returned_results": 2,
"time_resize": 43.78,
"time_search": 265.11,
"time_total": 310.04
}
}
JSON (with generate_overlay)¶
{
"method": "search",
"status": "ok",
"error": [],
"query_image": {
"filepath": "query.jpg"
},
"result": [
{
"filepath": "path/folder/match1.png",
"score": 100,
"match_percent": 100,
"query_overlap_percent": 100,
"target_overlap_percent": 99.98,
"metadata": {
"image_id": "dd8d-6dc8-bf3f"
},
"query_match_rect": {
"left": 2.8,
"right": 92.67,
"top": 12.44,
"bottom": 83.78
},
"target_match_rect": {
"left": 10.36,
"right": 98.5,
"top": 14.56,
"bottom": 87.89
},
"overlay": "overlay/?query=query.jpg&target=path/folder/match1.png&sc_2=1.00139&tr_2_x=0.0580673&tr_2_y=-0.612057&fd_2_z=1401.39&fd_2_x=400.446&fd_2_y=300.0&rot_1_y=0.349066&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=0.00134855&rot_2_x=0.00343397&rot_2_y=0.35174&fd_1_y=300.0&fd_1_x=400.446&fd_1_z=1400.89"
},
{
"filepath": "path/folder/match2.png",
"score": 9.8,
"match_percent": 17.56,
"query_overlap_percent": 77.02,
"target_overlap_percent": 80.48,
"metadata": {
"image_id": "db9561-7cecb6"
},
"query_match_rect": {
"left": 11.4,
"right": 61.7,
"top": 32.65,
"bottom": 73.8
},
"target_match_rect": {
"left": 33.1,
"right": 69.45,
"top": 27.62,
"bottom": 89.63
},
"overlay": "overlay/?query=query.jpg&target=path/folder/match2.png&sc_2=0.990622&tr_2_x=-139.649&tr_2_y=-103.786&fd_2_z=1171.51&fd_2_x=400.446&fd_2_y=300.0&rot_1_y=0.0&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=-0.00281038&rot_2_x=-0.00213862&rot_2_y=0.00861092&fd_1_y=236.0&fd_1_x=290.786&fd_1_z=1053.57"
}
],
"stats": {
"total_results": 2,
"total_filtered_results": 2,
"total_returned_results": 2,
"time_resize": 43.78,
"time_search": 265.11,
"time_total": 310.04
}
}
XML¶
<?xml version="1.0" encoding="utf-8"?>
<data>
<method>search</method>
<status>ok</status>
<error/>
<query_image>
<filepath>query.jpg</filepath>
</query_image>
<result>
<item>
<filepath>path/folder/match1.png</filepath>
<score>100.0</score>
<match_percent>100.0</match_percent>
<query_overlap_percent>100.0</query_overlap_percent>
<target_overlap_percent>99.98</target_overlap_percent>
<metadata>
<image_id>dd8d-6dc8-bf3f</image_id>
</metadata>
<query_match_rect>
<left>2.8</left>
<right>92.67</right>
<top>12.44</top>
<bottom>83.78</bottom>
</query_match_rect>
<target_match_rect>
<left>10.36</left>
<right>98.5</right>
<top>14.56</top>
<bottom>87.89</bottom>
</target_match_rect>
</item>
<item>
<filepath>path/folder/match2.png</filepath>
<score>9.80</score>
<match_percent>17.56</match_percent>
<query_overlap_percent>77.04</query_overlap_percent>
<target_overlap_percent>80.48</target_overlap_percent>
<metadata>
<image_id>db9561-7cecb6</image_id>
</metadata>
<query_match_rect>
<left>11.4</left>
<right>61.7</right>
<top>32.65</top>
<bottom>73.8</bottom>
</query_match_rect>
<target_match_rect>
<left>33.1</left>
<right>69.45</right>
<top>27.62</top>
<bottom>89.63</bottom>
</target_match_rect>
</item>
</result>
<stats>
<total_results>2</total_results>
<total_filtered_results>2</total_filtered_results>
<total_returned_results>2</total_returned_results>
<time_resize>43.78</time_resize>
<time_search>265.11</time_search>
<time_total>310.04</time_total>
</stats>
</data>
XML (with generate_overlay)¶
<?xml version="1.0" encoding="utf-8"?>
<data>
<method>search</method>
<status>ok</status>
<error/>
<query_image>
<filepath>query.jpg</filepath>
</query_image>
<result>
<item>
<filepath>path/folder/match1.png</filepath>
<score>100.0</score>
<match_percent>100.0</match_percent>
<query_overlap_percent>100.0</query_overlap_percent>
<target_overlap_percent>99.98</target_overlap_percent>
<metadata>
<image_id>dd8d-6dc8-bf3f</image_id>
</metadata>
<query_match_rect>
<left>2.8</left>
<right>92.67</right>
<top>12.44</top>
<bottom>83.78</bottom>
</query_match_rect>
<target_match_rect>
<left>10.36</left>
<right>98.5</right>
<top>14.56</top>
<bottom>87.89</bottom>
</target_match_rect>
<overlay>overlay/?query=query.jpg&target=path/folder/match1.png&sc_2=1.00139&tr_2_x=0.0580673&tr_2_y=-0.612057&fd_2_z=1401.39&fd_2_x=400.446&fd_2_y=300.0&rot_1_y=0.349066&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=0.00134855&rot_2_x=0.00343397&rot_2_y=0.35174&fd_1_y=300.0&fd_1_x=400.446&fd_1_z=1400.89</overlay>
</item>
<item>
<filepath>path/folder/match2.png</filepath>
<score>9.80</score>
<match_percent>17.56</match_percent>
<query_overlap_percent>77.04</query_overlap_percent>
<target_overlap_percent>80.48</target_overlap_percent>
<metadata>
<image_id>db9561-7cecb6</image_id>
</metadata>
<query_match_rect>
<left>11.4</left>
<right>61.7</right>
<top>32.65</top>
<bottom>73.8</bottom>
</query_match_rect>
<target_match_rect>
<left>33.1</left>
<right>69.45</right>
<top>27.62</top>
<bottom>89.63</bottom>
</target_match_rect>
<overlay>overlay/?query=query.jpg&target=path/folder/match2.png&sc_2=0.990622&tr_2_x=-139.649&tr_2_y=-103.786&fd_2_z=1171.51&fd_2_x=400.446&fd_2_y=300.0&rot_1_y=0.0&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=-0.00281038&rot_2_x=-0.00213862&rot_2_y=0.00861092&fd_1_y=236.0&fd_1_x=290.786&fd_1_z=1053.57</overlay>
</item>
</result>
<stats>
<total_results>2</total_results>
<total_filtered_results>2</total_filtered_results>
<total_returned_results>2</total_returned_results>
<time_resize>43.78</time_resize>
<time_search>265.11</time_search>
<time_total>310.04</time_total>
</stats>
</data>