Tutorial - Searching

Now that we have some images in our collection (Tutorial - Adding images) we are ready to search among them.

Searching for an image

You can search for an image by downloading it from the web. Put your company name where it says <company>, of course, and you might need to add your username and password, like https://username:password@matchengine...

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

The cURL command creates a POST request which says send two parameters to your MatchEngine API. The first, url, tells the API to download the image and search for it in your collection. The second parameter says to make the result easy to read, which is handy here but not needed in production code.

Alternatively, since the image is in your collection, it would be faster to use

curl https://matchengine.tineye.com/<company>/rest/search/    \
    -F "filepath=example2.jpg"

In either case, what comes back should be

{
    "status": "ok",
    "error": [],
    "method": "search",
    "result": [
        {
            "match_percent": 100,
            "score": 100,
            "target_overlap_percent": 100,
            "query_overlap_percent": 99.99,
            "filepath": "example2.jpg"
        },
        {
            "match_percent": 29.22,
            "score": 20.20,
            "target_overlap_percent": 83.59,
            "query_overlap_percent": 68.43,
            "filepath": "example3.jpg",
        }
    ]
}

The scores give an idea of the relative goodness 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 culling them. The overlap_percent values give an idea of how much cropping was involved.

Notice that example3.jpg matched on the background of the image, despite the different cropping.

Of course, you don’t have to use cURL, and probably won’t when you really get going, but it is a quick way to try things out. The complete description of the search request is at POST search.

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

../_images/364069_a1.jpg

example2.jpg: 447x300 pixels.

../_images/364070_a.jpg

example3.jpg: 312x300 pixels.