Request

To run these examples you will need to substitute your company name for your MatchEngine server (as supplied by Idée) in place of <company>. There is no test server available.

For security reasons, do not call the API directly from a client-side machine. Doing so would expose your password, and allow anyone to delete your images or add their own.

An example call to list the images in your MatchEngine collection:

https://matchengine.tineye.com/<company>/rest/list/

This call can be made from a web browser for debugging purposes.

Image queries and uploads are submitted in a request equivalent to an enctype="multipart/form-data" form.

Here is an add example using cURL:

curl https://matchengine.tineye.com/<company>/rest/add/     \
     -F "image=@1.jpg"                                      \
     -F "filepath=path/to/file.jpg"

The first -F option (image=@1.jpg) points to the file on your local machine. The second -F option (filepath=path/to/file.jpg) is the file path that you would like to give to the image on the MatchEngine server. If filepath is omitted, the file’s local path will be used.

The file path can be any arbitrary identifier you like for the image, and it does not need to end with .jpg or any other file extension. It is important that the file paths be unique because images with the same path will overwrite each other.

Common parameters

All calls contain the following general parameters:

Key Description
format (optional)

JSON or XML formatted output, can be either json or xml, defaults to json.

https://matchengine.tineye.com/<company>/rest/list/?format=xml
timeout (optional) The call will timeout after timeout seconds. Set to 0 for no timeout.
callback (optional)

When using JSON, the output will be wrapped in the given callback method. For example, if callback=handle_results is used, the output will look like this:

handle_results( ...json output... );

Image format and sizes

  • Uploaded images must be in JPEG, PNG, GIF, BMP, or TIFF format.
  • Animated images are not supported (such as animated GIFs or PNGs).
  • Uploaded images should be 300px in the smallest dimension for optimal performance. Images with both dimensions larger than 300px will be resized by the API. For example, an image 800x600px will be resized to 400x300px.