Using the TinEye API to determine if an image is a stock photo

Searching

Now that you’ve signed up and purchased a bundle, you’re ready to start searching. These examples will use the Python library for the TinEye API. The key used is the sandbox key, so you can copy and paste these examples to try them without using up your own searches.

First, we’ll need to install the Python library. From a terminal, execute the following commands:

python -m pip install pytineye

The following Python code will perform a search:

from pytineye import TinEyeAPIRequest

tineye_api_key = '6mm60lsCNIB,FwOWjJqA80QZHh9BMwc-ber4u=t^'

api = TinEyeAPIRequest('http://api.tineye.com/rest/', tineye_api_key)

results = api.search_url(url='http://www.tineye.com/images/meloncat.jpg')

The results variable will contain matches for the requested image from all types of sites, because we didn’t specify that we were only interested in stock photo sites. In the results, a match tagged as “stock” comes from a site that licenses stock photographs. Matches tagged as belonging to a “collection” come from sites with large collections of images (for example, flickr.com or wikipedia.com) that may provide more information about the origin and licensing terms of images. In order to limit the results to only stock photo sites, we can add the tags = 'stock' argument to the request:

stock_results = api.search_url(url='http://www.tineye.com/images/meloncat.jpg', tags='stock')

Now, the stock_results variable contains only matches from sites that TinEye has labelled as stock photo sites.

The example above shows how to search for a single image. If you need to search for a large batch of images, you will want to write a script to loop through your image collection. Here’s a simple Python example that prints out whether an image was found on a stock site or not, for each image in a list of images:

from pytineye import TinEyeAPIRequest

# This is the TinEye API sandbox key
# They will always search for the same image, regardless of which images you provide

tineye_api_key = '6mm60lsCNIB,FwOWjJqA80QZHh9BMwc-ber4u=t^'

api = TinEyeAPIRequest('http://api.tineye.com/rest/', tineye_api_key)

# Note that these are dummy URLs
# Please replace them with real URLs to make this example work
image_url_list = ('http://example.com/myimage1.jpg', 'http://example.com/myimage2.jpg',)

for image_url in image_url_list:
    try:
        stock_results = api.search_url(url=image_url, tags='stock', limit=10)

        if stock_results.stats['total_filtered_results'] > 0:
            print(image_url + ' has matches on stock sites!')
    except Exception:
       print("There was an error searching for " + image_url)

Interpreting your results

To understand the results returned by the API, it’s important to understand some of the terminology that we use to describe matches. A website might have more than one matching version of an image. For example, a website might have a matching thumbnail image, a matching full-sized image and a matching banner image. These will all be separate matches.

A backlink is a specific occurence of a match on a webpage. For example, if a website uses the matching thumbnail on three different pages, the thumbnail match will have three backlinks, one for each page.

With that in mind, here’s part of the raw JSON response from one of the above API requests. You won’t need to interact with the JSON if you’re using one of our libraries but the JSON is helpful in illustrating the results you will get from the TinEye API:

{
  "stats": {
    "total_results": 8536,
    "total_collection": 97,
    "total_filtered_results": 4,
    "total_stock": 4,
    "query_time": "0.33",
    "total_backlinks": 32372,
    "timestamp": "1539633760.50"
  },
  "code": 200,
  "results": {
    "matches": [
      {
        "image_url": "http://img.tineye.com/result/a53345e78d9f4162f888d4dac8f5915833a5647d7f1161cd82e9da2013b05eb3",
        "height": 204,
        "score": 70.588,
        "width": 240,
        "size": 48960,
        "domain": "foter.com",
        "overlay": "overlay/dca08fc6b2ec4b9e04f94a4e29223f6af3dd6555/a53345e78d9f4162f888d4dac8f5915833a5647d7f1161cd82e9da2013b05eb3?m21=-0.00118293&m22=1.46985&m23=0.320615&m11=1.46985&m13=-0.0417408&m12=0.00118293",
        "tags": [
          "stock"
        ],
        "filesize": 11991,
        "format": "JPEG",
        "backlinks": [
          {
            "backlink": "http://foter.com/Yoda/",
            "url": "http://farm1.static.flickr.com/15/22792155_34e72ac061_m.jpg",
            "crawl_date": "2013-08-01"
          }
        ],
        "query_hash": "dca08fc6b2ec4b9e04f94a4e29223f6af3dd6555"
      }, &hellip;.
  },
  "messages": []
}

The response includes statistics (“stats”) for the entire request, such as how many results and how many backlinks it returned and how long the query took. It also includes a list of matches. Each match gives statistics about the matching image including:

its height, width and size
the domain on which it was found
a link to the matching image on our server
an overlay comparing your search image with the image we found
tags that indicate whether this match is on a stock site or a collection site
a list of backlinks

Each backlink contains the original url at which the image file was hosted, a link to the page on which the image was found and the date on which we crawled it.

Please note that if an image has no matches listed as coming from “stock” sites, that doesn’t guarantee that it is not a stock photo; while we strive to crawl as much of the web as possible, there may be stock photo sites that we don’t have tagged or results that we haven’t crawled yet.