How to integrate Impresee Search API v2

This document describes how you can integrate Impresee visual search services into your online store.


Previous Steps

  • Obtain an Impresee application UUID this is a string with 36 characters. This code can be generated in the Impresee Console or you can ask us to generate one for you.
  • Get a jpg image to test the integration (for more details see image recommendations section).


Impresee’s image based search service is a REST service that takes a text and/or a query image and searches inside one or more catalogs. The service can be called by sending a POST request to the URL:


The body of this request is a JSON:

  1. search_image_base64: Query image encoded in base64 format.

An example of this JSON can be seen below


Remember: To perform a visual search you DO NOT need to include the search_text unless you really want to search using both image and text

In order to reduce the size of the request, clients can send a compressed message by following this steps:

  1. Add the Content-Encoding: gzip header to the request.
  2. Send a compressed JSON (using theGZip algorithm).

By doing these steps, the server will first decompress the message and then resolve the search. Please note that compressing the search message is critical for obtaining good upload times.



Once the server has finished performing the search process it will return a JSON with the following fields:

  • impresee_version: API version
  • status: Exit status of the search process. 0 means that there were no errors, while 1 indicates that an error occurred.
  • error_message: Empty if status value is 0.
  • query_url: URL where the query can be found.
  • search_uid: Unique id of the search.
  • products: Array of products which images appear similar to the query. The array is ordered by the product’s similarity to the query, meaning that the first product is the most similar. Each product has five fields:
    • rank: Position in the result list. A value of 1 indicates that product is the most similar to the query.
    • product_url: URL of the product inside the e-commerce site.
    • product_image: URL of the main image of the product
    • product_texts: List of product texts objects. Each of them has two fields:
      • code: Code of the associated text
      • value: Value associated to the code, which is specific to the product itself
    • product_categories: List of categories which the product belongs to. Each category is an object with one field:
      • code: Category code.
    • texts_codes: A list of objects that map each text code to a readable string. Each object has two fields:
      • code: A text code
      • name: String associated to that text code
    • categories_codes: A list of objects that map each category code to a readable string. Each object has two fields:
      • code: A category code
      • name: String associated to that category code

Please note that the size of this JSON can be around 50KB. In order to reduce the time it takes the client to download the response, Impresee servers support sending a compressed JSON as a response. To ask the server to send a compressed response the following must be done:

  1. Ask the server to compress the search result by adding an Accept-Encoding: gzip header to the search request. Note that the server may decide not to compress the JSON if it is too small.
  2. Receive the response from the server and check whether it contains the Content-Encoding: gzip header or not. If it does, the body has been compressed with the GZip algorithm.
  3. Decompress the body and parse the JSON

Below you can find an example of a search result:

Image Recommendations

In order to obtain both good search results and good upload times, there are two considerations that need to be taken:

  1. Size and quality of the image: A large image with high quality is usually very big (we are talking about megabytes). Uploading images of these characteristics can take too long, without bringing any advantage in terms of the quality of the search results. We recommend resizing the image and changing its quality before encoding it to base64. The recommended values are:
  • Longest side of 480 pixels.
  • Quality of 75%.

This should result in a filesize close to 50KB.

  1. The object in the query image should be centered: To obtain good search results the object that is being looked for must be in the center of the image.

Note that this means that images should be cropped before searching, so that they mostly consider the object of interest (unless you’re using our Snap the Look feature).