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).

API rate limiting

Please single thread your application while using the TinEye API. That is, wait for a response before starting another search. Failure to do so will result in much longer than usual search times.

By default, the TinEye API allows a maximum of 30 searches per minute. You will get a warning message if you are over this limit. If you need to regularly perform searches at a higher rate, please contact us with details about your needs.

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": []
}