pytineye - Python client for the TinEye API

pytineye is a Python client for the TinEye API.

TinEyeAPIRequest

class pytineye.TinEyeAPIRequest(api_url='https://api.tineye.com/rest/', api_key='')

Class to ease communication with the TinEye API server.

Establish a connection to the API:

>>> from pytineye import TinEyeAPIRequest
>>> api = TinEyeAPIRequest(
...     api_url='https://api.tineye.com/rest/',
...     api_key='your_api_key'
... )

Searching for an image using an image URL:

>>> api.search_url(url='https://tineye.com/images/meloncat.jpg')
TinEyeResponse(...)

Searching for an image using image data:

>>> fp = open('meloncat.jpg', 'rb')
>>> data = fp.read()
>>> api.search_data(data=data)
TinEyeResponse(...)
>>> fp.close()

Getting information about your search bundle:

>>> api.remaining_searches()
{'bundles': [{'expire_date': datetime.datetime(2023, 3, 9, 14, 9, 12),
   'remaining_searches': 7892,
   'start_date': datetime.datetime(2021, 3, 10, 14, 9, 12)},
  {'expire_date': datetime.datetime(2019, 3, 23, 9, 52, 46),
   'remaining_searches': 50000,
   'start_date': datetime.datetime(2021, 3, 24, 9, 52, 45)}],
 'total_remaining_searches': 57892}

Getting an image count:

>>> api.image_count()
48560880094
image_count(**kwargs)

Lists the number of indexed images on TinEye.

  • kwargs, to pass extra arguments intended for debugging.

Returns: TinEye image count.

remaining_searches(**kwargs)

Lists the number of searches you have left in your current active block.

  • kwargs, to pass extra arguments intended for debugging.

Returns: a dictionary with remaining searches, start time and end time of block.

search_data(data, offset=0, limit=100, sort='score', order='desc', **kwargs)

Perform searches on the TinEye index using image data.

  • data, image data to use for searching.

  • offset, offset of results from the start, defaults to 0.

  • limit, number of results to return, defaults to 100.

  • sort, sort results by score, file size (size), or crawl date (crawl_date), defaults to descending (desc).

  • order, sort results by ascending (asc) or descending criteria.

  • kwargs, to pass extra arguments intended for debugging.

Returns: a TinEye Response object.

search_url(url, offset=0, limit=100, sort='score', order='desc', **kwargs)

Perform searches on the TinEye index using an image URL.

  • url, the URL of the image that will be searched for, must be urlencoded.

  • offset, offset of results from the start, defaults to 0.

  • limit, number of results to return, defaults to 100.

  • sort, sort results by score, file size (size), or crawl date (crawl_date), defaults to descending (desc).

  • order, sort results by ascending (asc) or descending criteria.

  • kwargs, to pass extra arguments intended for debugging.

Returns: a TinEye Response object.

TinEyeResponse

class pytineye.TinEyeResponse(matches, stats)

Represents a response from the API.

Attributes:

  • matches, a list of Match objects.

  • stats, stats for this search.

Match

class pytineye.Match(image_url, domain, score, width, height, size, image_format, filesize, overlay, tags=None, backlinks=None)

Represents an image match.

Attributes:

  • image_url, link to the result image.

  • domain, domain this result was found on.

  • score, a number (0 to 100) that indicates how closely the images match.

  • width, image width in pixels.

  • height, image height in pixels.

  • size, image area in pixels.

  • format, image format.

  • filesize, image size in bytes.

  • overlay, overlay URL.

  • backlinks, a list of Backlink objects pointing to the original websites and image URLs.

  • tags, whether this match belongs to a collection or stock domain.