Responses¶
All requests will be replied to with a JSON or XML string containing the documented variables for each method.
All JSON responses will contain a dictionary with keys while XML will contain elements under the root.
| Key | Description |
|---|---|
| query_image | Information about the query image. This will appear for search calls. |
| status | String containing one of ok, warn, fail. |
| method | String containing the name of the method that was called. |
| error | List of error strings, describing any errors if status is set to warn or fail. |
| result | List of response numbers, strings or response dictionaries. |
result is a list of dictionaries containing multiple keys for a search call:
| 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. A match_percent less than 10.0 indicates a very small matching region that may contain only few matching letters from two similar words. These kind of matches can safely be thresholded out. |
| query_overlap_percent | How much the query image overlaps the collection image, as a percentage. |
| target_overlap_percent | How much the collection image overlaps the query image, as a percentage. |
| overlay | A URL pointing to the overlay for a search. |
| metadata | Metadata pertaining to the collection image’s label. Available metadata is:
|
Example response to a search request¶
JSON¶
{
"status": "ok",
"method": "search",
"error": [],
"query_image": {
"filepath": "loudenne.jpg",
"metadata": {
"vintage_year": 2009,
"vintage_rect": {
"left": 12.83,
"right": 20.5,
"top": 19.2,
"bottom": 22.2
},
"variety_type": "Sauvignon Blanc",
"variety_rect": {
"left": 21.54,
"right": 67.32,
"top": 34.42,
"bottom": 42.74
},
"label_rect": {
"left": 2.83,
"right": 30.33,
"top": 0,
"bottom": 30
}
}
},
"result": [
{
"filepath": "path/folder/match1.png",
"score": 28.6,
"match_percent": 38.3,
"query_overlap_percent": 71.13,
"target_overlap_percent": 100,
"overlay": "overlay/?query=loudenne.jpg&target=path/folder/match1.png&sc_2=0.354561&tr_2_x=16.034&tr_2_y=5.55432&fd_2_z=1173.62&fd_2_x=224.0&fd_2_y=364.0&rot_1_y=0.0&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=-0.0265357&rot_2_x=-0.309258&rot_2_y=0.0772559&fd_1_y=149.919&fd_1_x=99.5&fd_1_z=464.839",
"metadata": {
"vintage_year": "2006",
"vintage_rect": {
"left": 27.6,
"right": 44.83,
"top": 56.8,
"bottom": 62.6
},
"variety_type": "Sauvignon Blanc",
"variety_rect": {
"left": 11.52,
"right": 46.81,
"top": 23.55,
"bottom": 36.84
},
"label_rect": {
"left": 0,
"right": 74.66,
"top": 0,
"bottom": 72.7
}
}
},
{
"filepath": "path/folder/match2.png",
"score": 21.5,
"match_percent": 44.08,
"query_overlap_percent": 100,
"target_overlap_percent": 82.81,
"overlay": "overlay/?query=loudenne.jpg&target=path/folder/match2.png&sc_2=0.575815&tr_2_x=-3.93397&tr_2_y=8.21193&fd_2_z=883.189&fd_2_x=188.973&fd_2_y=252.705&rot_1_y=-0.349066&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=0.0693209&rot_2_x=-0.157565&rot_2_y=-0.388874&fd_1_y=149.919&fd_1_x=99.5&fd_1_z=464.839",
"metadata": {
"vintage_year": "2005",
"vintage_rect": {
"left": 24.83,
"right": 36.3,
"top": 35.1,
"bottom": 38.8
},
"variety_type": "Sangiovese",
"variety_rect": {
"left": 21.32,
"right": 43.63,
"top": 46.36,
"bottom": 52.31
},
"label_rect": {
"left": 2.66,
"right": 58.6,
"top": 0,
"bottom": 48.5
}
}
}
]
}
XML¶
<?xml version="1.0" encoding="utf-8"?>
<data>
<status>ok</status>
<method>search</method>
<error/>
<query_image>
<filepath>loudenne.jpg</filepath>
<metadata>
<vintage_year>2009</vintage_year>
<vintage_rect>
<left>12.83</left>
<right>20.5</right>
<top>19.2</top>
<bottom>22.2</bottom>
</vintage_rect>
<variety_type>Sauvignon Blanc</variety_type>
<variety_rect>
<left>21.54</left>
<right>67.32</right>
<top>34.42</top>
<bottom>42.74</bottom>
</variety_rect>
<label_rect>
<left>2.83</left>
<right>30.33</right>
<top>0</top>
<bottom>30</bottom>
</label_rect>
</metadata>
</query_image>
<result>
<item>
<filepath>path/folder/match1.png</filepath>
<score>28.6</score>
<match_percent>38.3</match_percent>
<query_overlap_percent>71.13</query_overlap_percent>
<target_overlap_percent>100.0</target_overlap_percent>
<overlay>overlay/?query=loudenne.jpg&target=path/folder/match1.png&sc_2=0.354561&tr_2_x=16.034&tr_2_y=5.55432&fd_2_z=1173.62&fd_2_x=224.0&fd_2_y=364.0&rot_1_y=0.0&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=-0.0265357&rot_2_x=-0.309258&rot_2_y=0.0772559&fd_1_y=149.919&fd_1_x=99.5&fd_1_z=464.839</overlay>
<metadata>
<vintage_year>2006</vintage_year>
<vintage_rect>
<left>27.6</left>
<right>44.83</right>
<top>56.8</top>
<bottom>62.6</bottom>
</vintage_rect>
<variety_type>Sauvignon Blanc</variety_type>
<variety_rect>
<left>11.52</left>
<right>46.81</right>
<top>23.55</top>
<bottom>36.84</bottom>
</variety_rect>
<label_rect>
<left>0</left>
<right>74.66</right>
<top>0</top>
<bottom>72.7</bottom>
</label_rect>
</metadata>
</item>
<item>
<filepath>path/folder/match2.png</filepath>
<score>21.5</score>
<match_percent>44.08</match_percent>
<query_overlap_percent>100.0</query_overlap_percent>
<target_overlap_percent>82.81</target_overlap_percent>
<overlay>overlay/?query=loudenne.jpg&target=path/folder/match2.png&sc_2=0.575815&tr_2_x=-3.93397&tr_2_y=8.21193&fd_2_z=883.189&fd_2_x=188.973&fd_2_y=252.705&rot_1_y=-0.349066&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=0.0693209&rot_2_x=-0.157565&rot_2_y=-0.388874&fd_1_y=149.919&fd_1_x=99.5&fd_1_z=464.839</overlay>
<metadata>
<vintage_year>2005</vintage_year>
<vintage_rect>
<left>24.83</left>
<right>36.3</right>
<top>35.1</top>
<bottom>38.8</bottom>
</vintage_rect>
<variety_type>Sangiovese</variety_type>
<variety_rect>
<left>21.32</left>
<right>43.63</right>
<top>46.36</top>
<bottom>52.31</bottom>
</variety_rect>
<label_rect>
<left>2.66</left>
<right>58.6</right>
<top>0</top>
<bottom>48.5</bottom>
</label_rect>
</metadata>
</item>
</result>
</data>