General

Tutorials

API documentation

Searching

Searching for an image

Now that you have added some images in the first tutorial, you are ready to search your collection.

As with adding an image, you can search for an image by specifying the url where that image can be found or by uploading an image file from your server. In this tutorial we will search using a url. In all of the examples replace <company> with your WineEngine account name. If you are using password-based authentication you must also add your username and password (i.e. https://username:password@wineengine...).

curl https://wineengine.tineye.com/<company>/rest/search/                        \
    -F "url=https://img.tineye.com/samples/tutorials/balbas_table.jpg"

The cURL command issues a POST request which sends a parameter, url, to your WineEngine API, telling the API to download the image and search for it in your collection.

If there are no errors the server should reply with:

{
  "status": "ok",
  "method": "search",
  "error": [],
  "query_image": {
    "filepath": "balbas_table.jpg",
    "metadata": {
      "label_rect": {
        "top": 0,
        "right": 552,
        "bottom": 640,
        "left": 120
      }
    }
  },
  "result": [
    {
      "filepath": "example2.jpg",
      "score": 22.0,
      "match_percent": 13.9,
      "query_overlap_percent": 37.82,
      "target_overlap_percent": 89.23,
      "metadata": {
        "vintage_year": "2011",
        "vintage_rect": {
          "top": 346,
          "right": 230,
          "bottom": 381,
          "left": 149
        },
        "label_rect": {
          "top": 0,
          "right": 342,
          "bottom": 576,
          "left": 30
        }
      }
    },
    {
      "filepath": "example1.jpg",
      "score": 21.9,
      "match_percent": 14.41,
      "query_overlap_percent": 42.47,
      "target_overlap_percent": 83.94,
      "metadata": {
        "vintage_year": "2011",
        "vintage_rect": {
          "top": 518,
          "right": 361,
          "bottom": 571,
          "left": 240
        },
        "label_rect": {
          "top": 0,
          "right": 552,
          "bottom": 892,
          "left": 48
        }
      }
    }
  ]
}

The scores give an idea of the relative quality of the matches, but note that a low score doesn’t necessarily mean a poor match. Scores are best used for ordering results, rather than eliminating them. The overlap_percent values give an idea of how much cropping was involved.

The complete description of the search request is available at Search.

Here is what the example images used above look like. Note that they have been pre-scaled to the recommended size, 600 pixels in the smallest dimension:

balbas_table.jpg: 600x800 pixels.

../_images/balbas_table.jpg

example1.jpg: 600x892 pixels.

../_images/balbas_label.jpg

example2.jpg: 750x600 pixels.

../_images/balbas_crop.jpg

Now that you’ve tried searching, learn how to view your collection images and generate overlays in the next tutorial: Working with images.