General

Tutorials

API documentation

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 String with the query image’s path.
score String with relevance score.
match_percent How much the images match each other, as a percentage. A match_percent less than 10.0 indicates a very small matching region that can 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 target image, as a percentage.
target_overlap_percent How much the target image overlaps the query image, as a percentage.
overlay URL pointing to an image used to generate overlays.
metadata

Metadata pertaining to the result image’s label. Available metadata is:

  • vintage_year: The vintage year for this wine, if available.
  • vintage_rect: Position of the vintage year if available.
  • label_rect: Position of the wine label in the image.

Example response to a search request

JSON

{
  "status": "ok",
  "method": "search",
  "error": [],
  "query_image": {
    "filepath": "loudenne.jpg",
    "metadata": {
      "vintage_year": 2009,
      "vintage_rect": {
        "top": 192,
        "right": 123,
        "bottom": 222,
        "left": 77
      },
      "label_rect": {
        "top": 0,
        "right": 182,
        "bottom": 300,
        "left": 17
      }
    }
  },
  "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": {
          "top": 568,
          "right": 269,
          "bottom": 626,
          "left": 162
        },
        "label_rect": {
          "top": 0,
          "right": 448,
          "bottom": 727,
          "left": 0
        }
      }
    },
    {
      "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": {
          "top": 350,
          "right": 216,
          "bottom": 388,
          "left": 149
        },
        "label_rect": {
          "top": 0,
          "right": 348,
          "bottom": 485,
          "left": 16
        }
      }
    }
  ]
}

XML

<?xml version="1.0" encoding="utf-8"?>
<data>
  <status>ok</status>
  <method>search</method>
  <error/>
  <query_image>
    <filepath>loudenne_2009.jpg</filepath>
    <metadata>
      <vintage_year>2009</vintage_year>
      <vintage_rect>
        <top>192</top>
        <right>123</right>
        <bottom>222</bottom>
        <left>77</left>
      </vintage_rect>
      <label_rect>
        <top>0</top>
        <right>182</right>
        <bottom>300</bottom>
        <left>17</left>
      </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&amp;target=path/folder/match1.png&amp;sc_2=0.354561&amp;tr_2_x=16.034&amp;tr_2_y=5.55432&amp;fd_2_z=1173.62&amp;fd_2_x=224.0&amp;fd_2_y=364.0&amp;rot_1_y=0.0&amp;rot_1_x=0.0&amp;rot_1_z=0.0&amp;rot_2_z=-0.0265357&amp;rot_2_x=-0.309258&amp;rot_2_y=0.0772559&amp;fd_1_y=149.919&amp;fd_1_x=99.5&amp;fd_1_z=464.839</overlay>
      <metadata>
        <vintage_year>2006</vintage_year>
        <vintage_rect>
          <top>568</top>
          <right>269</right>
          <bottom>626</bottom>
          <left>162</left>
        </vintage_rect>
        <label_rect>
          <top>0</top>
          <right>448</right>
          <bottom>727</bottom>
          <left>0</left>
        </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&amp;target=path/folder/match2.png&amp;sc_2=0.575815&amp;tr_2_x=-3.93397&amp;tr_2_y=8.21193&amp;fd_2_z=883.189&amp;fd_2_x=188.973&amp;fd_2_y=252.705&amp;rot_1_y=-0.349066&amp;rot_1_x=0.0&amp;rot_1_z=0.0&amp;rot_2_z=0.0693209&amp;rot_2_x=-0.157565&amp;rot_2_y=-0.388874&amp;fd_1_y=149.919&amp;fd_1_x=99.5&amp;fd_1_z=464.839</overlay>
      <metadata>
        <vintage_year>2005</vintage_year>
        <vintage_rect>
          <top>350</top>
          <right>216</right>
          <bottom>388</bottom>
          <left>149</left>
        </vintage_rect>
        <label_rect>
          <top>0</top>
          <right>348</right>
          <bottom>485</bottom>
          <left>16</left>
        </label_rect>
      </metadata>
    </item>
  </result>
</data>