API Docs

How does it work?

API description

The service is delivered over HTTP or HTTPS as a REST API with responses delivered in JSON format.

The API is completely independent of your operating system, database system or development language. We provide and support API libraries in many development languages in order to make it even easier to integrate. You can see our current library list here.

Two good introductions to REST are xfront.com/REST-Web-Services.html and infoq.com/articles/rest-introduction.

More information on JSON can be found at json.org and en.wikipedia.org/wiki/JSON.

You can also view Libraries for the API, or read our developer FAQs.

Request format

GET request

All requests to the TinEye API are made via GET requests, with the exception of image uploads which are submitted via POST (equivalent to an encrypt="multipart/form-data" form).

Searching the TinEye API using cURL:

curl https://api.tineye.com/rest/search/ --get                                              \
     -d "api_key=LCkn,2K7osVwkX95K4Oy"                                                      \
     -d "api_sig=c29164f8aff7d732886f47fc2216c1a3292fab6d675b3c1ed45da619174fd4bd"          \
     -d "nonce=5e3800e6e1f1a301796da0fdea79cef7"                                            \
     -d "date=1490029747"                                                                   \
     -d "image_url=https%3A%2F%2Ftineye.com%2Fimages%2Fmeloncat.jpg"                        \
     -d "limit=2"

Listing the number of images available in the TinEye index using cURL:

curl https://api.tineye.com/rest/image_count/ --get                                         \
     -d "api_key=LCkn,2K7osVwkX95K4Oy"                                                      \
     -d "api_sig=6f7b964f7b0cb3d4d191babbaebfe1ca0b62e35496684d5a0a1b7e05cb97a17c"          \
     -d "nonce=6423f8ad27c897ffe608bc40416a7e9a"                                            \
     -d "date=1490029374"

POST request

To upload an image to the TinEye API via a POST request, please see the POST Request Example.

API authentication

For more information on authenticating against the TinEye API, please see TinEye API Authentication.

Response format

All requests will receive a JSON response string containing the documented variables for each method.

All responses will contain a dictionary with four keys:

stats A dictionary containing the current timestamp and the length of the query in seconds.
code HTTP status code of the response.
messages Information, warnings or errors from the API.
result List of response strings.

Image formats and sizes

The search image, uploaded or provided as a URL must be in either JPEG, PNG, GIF, BMP, or TIFF format. We do not support animations (such as animated GIF or PNG images).

For optimal performance, uploaded images should be at most 300px in size in the smallest dimension. Images with both dimensions larger than 300px will be resized by the API. For example, an image 800x600px in size will be resized to 400x300px.

Image overlays

For each search result we generate an overlay image which aligns the search and result images so they match up with each other, adjusting for crops, flips, translations and rotation. Each result will include a URL to generate an overlay image on the API server. To view the overlay, simply browse to the overlay URL provided (e.g. https://api.tineye.com/rest/<overlay_path>). You can use this URL to link to the overlay image directly in the src attribute of an HTML img tag.

The overlay image is composed of both the search and match images.

_static/images/sample_overlay.jpg

The left side of the overlay is the matched image. The right side is the search image.

By using JavaScript and CSS you can use the overlay image to switch between the matched image and the search image so you can easily see how the two images differ. Mouseover the following image to see how this can be done:

Example code:

<div style="background-image: url('<overlay URL>'); width: <image width>px; height: <image height>px; background-position: 0px center;"
 onmouseover="this.style.backgroundPosition='-<image width>px center'"
 onmouseout="this.style.backgroundPosition='0px center'"></div>

The example code aboves shows the left half of the overlay image to start (i.e. the matched image), and then switches to the right half when you mouseover the image (i.e. the search image).

Match scores

Each result includes a score from 0 to 100 indicating how much the matching image has been modified from the query image. By default, the results are ordered by descending scores so the first match returned is the strongest match.

Weaker matches may include partial matches and matches that are not relevant to your needs. For example, a logo, some text or the background in the result image may match part of your search image, but the overall images are not the same. This is the nature of our image searching: it looks for identical regions in images and cannot decide that a matching logo, text or background is a bad or irrelevant match for you.

A common mistake is attempting to use a score cut-off to eliminate bad matches. We generally recommend against this practice because it can easily eliminate good matches, too. For example, an exact copy of an image that has been used to make a thumbnail might have a lower score than a heavily-modified version of the query image at its original size.

For example, here is an original image:

_static/images/citrus_original.jpg

When searching for this image, you may find matches where the image is cropped or resized:

_static/images/citrus_crop_and_thumb.jpg

These are valid matches, but their scores are only 22.4 and 24.7, respectively.

On the other hand, consider the following matching images:

_static/images/hummingbird.jpg

These are clearly two different images, and yet the match score is 51.4, significantly higher than the legitimate matches shown above.

Some of our clients, especially very high-volume clients, still decide to use a score threshold to eliminate weaker matches. This is fine, as long as your use case does not require finding small or heavily modified versions of images.

API rate limiting

By default, the TinEye API allows a maximum of 4 simultaneous requests. The API will return a “429 Too many requests” error if you attempt to exceed that limit. If you regularly need to perform more concurrent searches than allowed by the limit, please contact us with details about your requirements.

API methods

General arguments

You will need to provide the following arguments to all calls to authenticate your request:

api_key (Required) Your public key as provided by TinEye.
api_sig (Required) A unique signature.
nonce (Required) A unique random string of at least 8 characters.
date (Required) The Unix timestamp (number of seconds since January 1, 1970 00:00:00 GMT).

See the Authentication page for more details.

All methods optionally take these arguments:

pretty (Optional) Print JSON with indentation for easier reading. Set to true to enable. Useful for debugging.

Available methods

remaining_searches

Lists the number of searches you have left in your non-expired bundles.

Arguments

  • None

Response variables (results dictionary)

bundles

List of non-expired bundles with remaining searches. Each bundle entry has the following fields:

  • remaining_searches, number of remaining searches available in this bundle
  • start_date, start date of this bundle
  • end_date, end date of this bundle, when it will deactivate
total_remaining_searches Total number of searches remaining across all non-expired bundles.

Example query:

curl https://api.tineye.com/rest/remaining_searches/ --get                                  \
     -d "api_key=LCkn,2K7osVwkX95K4Oy"                                                      \
     -d "api_sig=829e6e7c58a5db588d9093f83eec406393ff62fc8bd95fe1c339d7179ceada2c"          \
     -d "nonce=a57a253eacc26ead4199c00deb1b1fde"                                            \
     -d "date=1490029267"

Response:

{
    "stats": {
        "timestamp": "1490029267.12",
        "query_time": "0.07"
    },
    "code": 200,
    "messages": [],
    "results": {
        "bundles": [
            {
                "remaining_searches": 719,
                "start_date": "2016-12-17 03:42:50 UTC",
                "expire_date": "2018-12-17 03:42:50 UTC"
            },
            {
                "remaining_searches": 10000,
                "start_date": "2017-02-25 16:31:09 UTC",
                "expire_date": "2019-02-25 16:31:09 UTC"
            },
            {
                "remaining_searches": 10000,
                "start_date": "2017-03-19 09:50:16 UTC",
                "expire_date": "2019-03-19 09:50:16 UTC"
            }
        ],
        "total_remaining_searches": 20719
    }
}

image_count

Gets the number of indexed images.

Arguments

  • None

Example query:

curl https://api.tineye.com/rest/image_count/ --get                                         \
     -d "api_key=LCkn,2K7osVwkX95K4Oy"                                                      \
     -d "api_sig=6f7b964f7b0cb3d4d191babbaebfe1ca0b62e35496684d5a0a1b7e05cb97a17c"          \
     -d "nonce=6423f8ad27c897ffe608bc40416a7e9a"                                            \
     -d "date=1490029374"

Response:

{
   "stats": {
       "timestamp": "1490029374.99",
       "query_time": "0.02"
   },
   "code": 200,
   "messages": [],
   "results": 18114111275
}

Error messages

There are three errors that you are likely to encounter when searching for images.

Error: the URL does not exist

{
   "stats": {
       "timestamp": "1331923111.71",
       "query_time": "0.51"
   },
   "code": 400,
   "messages": ["API_ERROR", "Couldn't download URL, caught exception: HTTPError()"],
   "results": []
}

Error: the image is corrupted or is not an image file

{
   "stats": {
       "timestamp": "1331923111.71",
       "query_time": "0.51"
   },
   "code": 500,
   "messages": ["API_ERROR", "cannot identify image file"],
   "results": []
}

Error: the image is visually too simple or is too small in size

{
   "stats": {
      "timestamp": "1331923111.71",
      "query_time": "0.51"
   },
   "code": 500,
   "messages": ["NO_SIGNATURE_ERROR", "Image too simple or too small to create unique signature."],
   "results": []
}