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

Publishers and designers can accumulate huge libraries of images that have been used across many of their projects. Unfortunately, it’s not always easy to keep records of where all of these images came from and under what terms they are licensed. TinEye can be used to manually search for images one at a time, but if you have hundreds or thousands of images in your library that approach becomes impractical. Fortunately, we have a solution to this problem: the TinEye API.

Now that you’ve signed up and purchased a bundle, you’re ready to start searching. The examples below use the Python library for the TinEye API.

Using the Sandbox key

The key used is the sandbox key, so you can copy and paste these examples to try them without using up your own searches. No matter what query image you use, all results will be for the "melon cat" image.

If you use your own API key and an image other than the melon cat, you'll get real results!

Performing the search

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

# This is the TinEye API sandbox key.
# Using it will always return results for the sample melon cat image, regardless      
# of which image you search for.

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

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

results = api.search_url(
    url='https://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='https://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.

Searching for multiple images

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.
# Using it will always return results for the sample melon cat image, regardless      
# of which image you search for.

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

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

# Note that these are dummy URLs that will only work with the sandbox
# Please replace them with real URLs to make this example work with your key
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. 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/a53345e78d9f4162f888d4dac8f5915833a5647d7f1161cd82e 
9da2013b05eb3",
        "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"
      }, ...
  },
  "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.