Requests¶

To run these examples you will need to substitute your company name for your WineEngine server (as supplied by TinEye) 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 WineEngine collection:

https://wineengine.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://wineengine.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 WineEngine 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://wineengine.tineye.com/<company>/rest/list/?format=xml
timeout (optional)	The call will timeout after timeout seconds. Set to 0 for no timeout.

Image formats and sizes¶

Images uploaded to the API¶

Uploaded images must be JPEG, PNG, WEBP, AVIF, GIF, BMP or TIFF format.
Animated images are not supported (such as animated GIFs, PNGs, WEBPs and AVIFs).
Uploaded images should be 1000 pixels in the smallest dimension for optimal performance. Images with both dimensions larger than 1000 pixels will be resized by the API. For example, an image 1800x1500 pixels will be resized to 1200x1000 pixels.

Images taken with a mobile device¶

Mobile images should be 1000 pixels in the smallest dimension.
Recommended average image size is 100 kB.
Use a quality setting of 85% or higher for JPEG images.

Name Filtering¶

You can limit the results of some methods to images whose names or paths match certain patterns using the name_filter and path_filter parameters. These filters use a subset of regular expressions:

Value	Meaning
`^abc`	Starts with `abc`
`xyz$`	Ends with `xyz`
`lmn`	Contains `lmn`
`^efg$`	Exactly matches `efg`
`.*`	Matches 0 or more of any character
`\`	Used to escape the special characters `^`, `$`, `.`, `*` and `\` if you need to match them literally

For example, if your collection filenames are of the format producttype-productname-MM-DD-YYYY, and you wanted to list all images of type shoes that were released in March 2022, and are in subfolders of /folder01/folder02/, then you could use the following command:

curl https://wineengine.tineye.com/<company>/rest/list/ --get   \
    -d "path_filter=^/folder01/folder02/"                       \
    -d "name_filter=^shoes-.*-03-.*-2022$"                      \
    -d "offset=0"                                               \
    -d "limit=200"

If your filename pattern was instead producttype.productname.MM.DD.YYYY, then to search for them you would need to escape the period characters:

curl https://wineengine.tineye.com/<company>/rest/list/ --get   \
    -d "path_filter=^/folder01/folder02/"                       \
    -d "name_filter=^shoes\..*\.03\..*\.2022$"                  \
    -d "offset=0"                                               \
    -d "limit=200"

Date Filtering¶

You can limit the results of some methods to images inserted in a certain date range using the after_date_filter and before_date_filter parameters. These filters expect dates in YYYY-MM-DD format.

For example, if you want to list all images inserted starting on 5th of February 2023 and ending on 9th of February 2023, then you could use the following command:

curl https://wineengine.tineye.com/<company>/rest/list/ --get   \
    -d "after_date_filter=2023-02-04"                           \
    -d "before_date_filter=2023-02-10"                          \
    -d "offset=0"                                               \
    -d "limit=100"