Table of Contents

Introduction

The TinEye Commercial API provides a programmatic interface to search the complete TinEye index. Search results contain all the information given for searches done via the website:

How does it work?

API Description

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

The API is completely independent of your operating system, database system or development language. Libraries and language bindings to support REST and JSON are available in all major languages and platforms.

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

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

Request Format

GET Request

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

Searching the TinEye API using cURL:

curl http://api.tineye.com/rest/search/ --get                                 \ 
     -d "api_key=1CMUPjlfBm*vL9ZvSqJO"                                        \ 
     -d "api_sig=9c5f48648cc48531b7e7679703bc2bda1a1713c7"                    \ 
     -d "nonce=fdsafDFdgtr234ae"                                              \ 
     -d "date=1250535183"                                                     \ 
     -d "image_url=http%3a%2f%2ftineye.com%2fimages%2ftineye_logo_big.png"    \ 
     -d "limit=2"
                    

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

curl http://api.tineye.com/rest/image_count/ --get                  \ 
     -d "api_key=1CMUPjlfBm*vL9ZvSqJO"                              \ 
     -d "api_sig=f9db2d379ac9c7aa8f6367d33184fa50ddf52265"          \ 
     -d "nonce=fdsafDFdgtr234ae"                                    \ 
     -d "date=1250535183"
                    

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 be replied to with a JSON 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 Format and Sizes

The uploaded image or URL must be either a JPEG, a PNG or GIF. 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

Whenever a search has results, the result will include a URL to generate an overlay image on the API server. The overlay image aligns the search and result images so they match up with each other, adjusting for crops, flips, translations and rotation. To generate and view the overlay, simply go to the overlay URL on the TinEye API (e.g. http://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 is a single image composed of a left and a right side, like the image below.

Sample overlay

The left side is the original image from the collection that the searched image was matched against. The right side is the image that was searched against the collection.

By using JavaScript and CSS you can use the overlay image to "overlap" the collection image and the search image so you can easily see how the search image differs from the collection image (if at all). 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 collection image), and then shows the right half when you mouseover the image (i.e. the searched 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 only allows up to 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 Idée
  • api_sig (Required), a unique signature
  • nonce (Required), a unique random string of at least 8 characters
  • date (Required), the unix epoch timestamp (number of seconds since January 1, 1970 00:00:00 GMT)

See the authentication page for more details.

All methods contain the following general arguments:

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

remaining_searches

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

Arguments:

  • None

Response variables (results dictionary)

  • remaining_searches, number of remaining searches available
  • start_date, start date of the active block
  • expire_date, expiry date of the active block

Example query:

curl http://api.tineye.com/rest/remaining_searches/ --get           \ 
     -d "api_key=1CMUPjlfBm*vL9ZvSqJO"                              \ 
     -d "api_sig=f9db2d379ac9c7aa8f6367d33184fa50ddf52265"          \ 
     -d "nonce=fdsafDFdgtr234ae"                                    \ 
     -d "date=1250535183"
                

Response:

{
    "stats": {
        "timestamp": "1250535183.20",
        "query_time": "0.01"
    },
    "code": 200,
    "messages": [],
    "results": {
        "remaining_searches": 24998,
        "start_date": "2009-09-18 16:01:49 UTC",
        "expire_date": "2009-11-02 16:01:49 UTC"
    }
}
                

image_count

Lists the number of indexed images.

Arguments:

  • None

Example query:

curl http://api.tineye.com/rest/image_count/ --get                  \ 
     -d "api_key=1CMUPjlfBm*vL9ZvSqJO"                              \ 
     -d "api_sig=f9db2d379ac9c7aa8f6367d33184fa50ddf52265"          \ 
     -d "nonce=fdsafDFdgtr234ae"                                    \ 
     -d "date=1250535183"
                

Response:

{
    "stats": {
        "timestamp": "1250524846.03",
        "query_time": "0.00"
    },
    "code": 200,
    "messages": [],
    "results": 1109463092
}
                

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

                
API Login